Skip to content
FacilydevelopersDashboard
Build with Facily
DocsREST APIsSubmit Dispute Evidence
Search the full API reference Esc to close

Submit Dispute Evidence

Payments · REST API reference

Get support
POST/v1/disputes/{dispute_id}/evidence/submit
Submit the dispute's evidence for review and answer the dispute as the processor now describes it (normally EVIDENCE_UPLOADED). 409 NO_EVIDENCE when nothing new is attached, and the dispute refusals as for attaching.

Authentication

Bearer API key or Facily session, subject to permissions and facility scope.

Authentication and scope

Request example

Replace bracketed path values with real IDs from your environment. The body, where shown, is generated from the schema and uses illustrative values.

cURL
curl --request POST \
  --url 'https://api.staging.facily.ai/v1/disputes/<DISPUTE_ID>/evidence/submit' \
  --header "Authorization: Bearer $FACILY_API_KEY"
An example for building your request, not an executed call. Check required fields, allowed values, and environment configuration before sending.

Parameters

dispute_idpath · stringrequired

Format: uuid

Responses

Expand a status to inspect its schema. Generated examples show structure and synthetic values.

200Successful Response
JSON · generated example
{
  "data": {
    "amount": "<VALUE_MATCHING_PATTERN>",
    "created_at": "2026-10-29T12:00:00Z",
    "facility_id": "00000000-0000-4000-8000-000000000001",
    "id": "00000000-0000-4000-8000-000000000001",
    "last_synced_at": "2026-10-29T12:00:00Z",
    "opened_at": "2026-10-29T12:00:00Z",
    "processor_dispute_id": "string",
    "provider": "string",
    "response_open": false,
    "state": "open",
    "status": "string",
    "evidence": [
      {
        "created_at": "2026-10-29T12:00:00Z",
        "dispute_id": "00000000-0000-4000-8000-000000000001",
        "file_size_bytes": 0,
        "id": "00000000-0000-4000-8000-000000000001",
        "mime_type": "string",
        "name": "string",
        "document_id": "00000000-0000-4000-8000-000000000001",
        "submitted_at": "2026-10-29T12:00:00Z"
      }
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

dataPaymentDisputeResponserequired

One chargeback or inquiry against a payment (spec section 14). Evidence is attached, removed and submitted through `/v1/disputes/{id}/evidence` (stax partner design S4).

Show data schema
amountstringrequired

The amount the cardholder disputed, as the processor states it. The chargeback actually booked is this capped by what the payment still had left to give, so the two can differ.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

created_atstringrequired

When Facily first recorded the dispute.

Format: date-time

evidenceDisputeEvidenceResponse[] | null

The evidence Facily sent, oldest first. Only on a single dispute; null in a list.

Show evidence schema
DisputeEvidenceResponse[] | null

The evidence Facily sent, oldest first. Only on a single dispute; null in a list.

Variant 1: DisputeEvidenceResponse[]
created_atstring

When it was sent to the processor.

Format: date-time

dispute_idstring

Format: uuid

document_idstring | null

The Facily document it was sent from. Null once that document is removed.

Format: uuid

Show document_id schema
string | null

The Facily document it was sent from. Null once that document is removed.

Variant 1: string
Variant 2: null
file_size_bytesinteger
idstring

Format: uuid

mime_typestring
namestring
submitted_atstring | null

When it was submitted for review. Submitted evidence cannot be removed.

Format: date-time

Show submitted_at schema
string | null

When it was submitted for review. Submitted evidence cannot be removed.

Variant 1: string
Variant 2: null
Variant 2: null
null
facility_idstringrequired

The facility whose payment is disputed.

Format: uuid

idstringrequired

Unique identifier for this dispute.

Format: uuid

last_synced_atstringrequired

When Facily last re-read this dispute from the processor.

Format: date-time

opened_atstringrequired

When the dispute was raised, as the processor dates it.

Format: date-time

payment_idstring | null

The disputed payment.

Format: uuid

Show payment_id schema
string | null

The disputed payment.

Variant 1: string
string
Variant 2: null
null
payment_numberstring | null

The disputed payment's operator-facing reference.

Show payment_number schema
string | null

The disputed payment's operator-facing reference.

Variant 1: string
string
Variant 2: null
null
processor_dispute_idstringrequired

The processor's own id for the dispute.

processor_transaction_idstring | null

The disputed transaction at the processor, where the processor names one.

Show processor_transaction_id schema
string | null

The disputed transaction at the processor, where the processor names one.

Variant 1: string
string
Variant 2: null
null
providerstringrequired

The processor the dispute came from, for example stax.

reasonstring | null

The card network's reason code, for example FRAUD.

Show reason schema
string | null

The card network's reason code, for example FRAUD.

Variant 1: string
string
Variant 2: null
null
refund_idstring | null

The chargeback refund a lost or accepted dispute produced. Null for an open dispute, for one resolved in the operator's favour, and for one whose payment had nothing left to give.

Format: uuid

Show refund_id schema
string | null

The chargeback refund a lost or accepted dispute produced. Null for an open dispute, for one resolved in the operator's favour, and for one whose payment had nothing left to give.

Variant 1: string
string
Variant 2: null
null
resolved_atstring | null

When the dispute closed. Null while it is open.

Format: date-time

Show resolved_at schema
string | null

When the dispute closed. Null while it is open.

Variant 1: string
string
Variant 2: null
null
respond_bystring | null

The processor's evidence deadline, where it gives one.

Format: date-time

Show respond_by schema
string | null

The processor's evidence deadline, where it gives one.

Variant 1: string
string
Variant 2: null
null
response_openbooleanrequired

True while evidence can be added, removed or submitted: open and before respond_by.

statestringrequired

Which family the status falls in. An unrecognised status is reported as open.

Values: "open", "resolved"

statusstringrequired

The processor's own status, verbatim: INQUIRY, OPEN, PENDING, EVIDENCE_UPLOADED, UPLOAD_FAILED, PREARBITRATION, WON, LOST or ACCEPTED. A value outside that set is possible and is treated as open.

tenant_idstring | null

The tenant whose payment is disputed.

Format: uuid

Show tenant_id schema
string | null

The tenant whose payment is disputed.

Variant 1: string
string
Variant 2: null
null
tenant_namestring | null

That tenant's display name, for the queue row.

Show tenant_name schema
string | null

That tenant's display name, for the queue row.

Variant 1: string
string
Variant 2: null
null
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
400Validation error
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
401Unauthenticated
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
403Permission denied
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
404Not found
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
409Business logic error
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
503Temporary failure
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
Continue exploringAll payments operations
Build something that works beautifully.

Facily API · Contract v1.200 · Reviewed October 29, 2026

Submit Dispute Evidence | Facily Developers