/v1/facilities/{facility_id}/disputesAuthentication
Bearer API key or Facily session, subject to permissions and facility scope.
Authentication and scopeRequest 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 --request GET \
--url 'https://api.staging.facily.ai/v1/facilities/<FACILITY_ID>/disputes' \
--header "Authorization: Bearer $FACILY_API_KEY"Try a request
Staging · read-onlyExplore your organization with a read-only request to staging.
Parameters
facility_idpath · string | stringrequiredFormat: uuid
statequery · stringDefault: "open" · Values: "open", "resolved"
limitquery · integerDefault: 100 · Minimum: 1 · Maximum: 200
Responses
Expand a status to inspect its schema. Generated examples show structure and synthetic values.
200Successful Response
{
"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"
},
"pagination": {
"has_more": false,
"limit": 0,
"cursor": "string",
"total_count": 0
},
"metrics": {
"cards": {},
"computed_at": "2026-10-29T12:00:00Z",
"is_stale": false,
"scope": "facility"
}
}application/json
dataPaymentDisputeResponse[]requiredShow data schema
amountstringrequiredThe 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_atstringrequiredWhen Facily first recorded the dispute.
Format: date-time
evidenceDisputeEvidenceResponse[] | nullThe evidence Facily sent, oldest first. Only on a single dispute; null in a list.
Show evidence schema
DisputeEvidenceResponse[] | nullThe evidence Facily sent, oldest first. Only on a single dispute; null in a list.
Variant 1: DisputeEvidenceResponse[]
created_atstringWhen it was sent to the processor.
Format: date-time
dispute_idstringFormat: uuid
document_idstring | nullThe Facily document it was sent from. Null once that document is removed.
Format: uuid
Show document_id schema
string | nullThe Facily document it was sent from. Null once that document is removed.
Variant 1: string
Variant 2: null
file_size_bytesintegeridstringFormat: uuid
mime_typestringnamestringsubmitted_atstring | nullWhen it was submitted for review. Submitted evidence cannot be removed.
Format: date-time
Show submitted_at schema
string | nullWhen it was submitted for review. Submitted evidence cannot be removed.
Variant 1: string
Variant 2: null
Variant 2: null
nullfacility_idstringrequiredThe facility whose payment is disputed.
Format: uuid
idstringrequiredUnique identifier for this dispute.
Format: uuid
last_synced_atstringrequiredWhen Facily last re-read this dispute from the processor.
Format: date-time
opened_atstringrequiredWhen the dispute was raised, as the processor dates it.
Format: date-time
payment_idstring | nullThe disputed payment.
Format: uuid
Show payment_id schema
string | nullThe disputed payment.
Variant 1: string
stringVariant 2: null
nullpayment_numberstring | nullThe disputed payment's operator-facing reference.
Show payment_number schema
string | nullThe disputed payment's operator-facing reference.
Variant 1: string
stringVariant 2: null
nullprocessor_dispute_idstringrequiredThe processor's own id for the dispute.
processor_transaction_idstring | nullThe disputed transaction at the processor, where the processor names one.
Show processor_transaction_id schema
string | nullThe disputed transaction at the processor, where the processor names one.
Variant 1: string
stringVariant 2: null
nullproviderstringrequiredThe processor the dispute came from, for example stax.
reasonstring | nullThe card network's reason code, for example FRAUD.
Show reason schema
string | nullThe card network's reason code, for example FRAUD.
Variant 1: string
stringVariant 2: null
nullrefund_idstring | nullThe 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 | nullThe 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
stringVariant 2: null
nullresolved_atstring | nullWhen the dispute closed. Null while it is open.
Format: date-time
Show resolved_at schema
string | nullWhen the dispute closed. Null while it is open.
Variant 1: string
stringVariant 2: null
nullrespond_bystring | nullThe processor's evidence deadline, where it gives one.
Format: date-time
Show respond_by schema
string | nullThe processor's evidence deadline, where it gives one.
Variant 1: string
stringVariant 2: null
nullresponse_openbooleanrequiredTrue while evidence can be added, removed or submitted: open and before respond_by.
statestringrequiredWhich family the status falls in. An unrecognised status is reported as open.
Values: "open", "resolved"
statusstringrequiredThe 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 | nullThe tenant whose payment is disputed.
Format: uuid
Show tenant_id schema
string | nullThe tenant whose payment is disputed.
Variant 1: string
stringVariant 2: null
nulltenant_namestring | nullThat tenant's display name, for the queue row.
Show tenant_name schema
string | nullThat tenant's display name, for the queue row.
Variant 1: string
stringVariant 2: null
nullmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequiredmetricsEmbeddedMetrics | nullShow metrics schema
EmbeddedMetrics | nullVariant 1: EmbeddedMetrics
cardsobjectrequiredcomputed_atstring | nullrequiredFormat: date-time
Show computed_at schema
string | nullVariant 1: string
stringVariant 2: null
nullis_stalebooleanrequiredscopestringrequiredValues: "facility", "portfolio"
Variant 2: null
nullpaginationPaginationBlockrequiredPagination metadata for list responses.
Show pagination schema
cursorstring | nullShow cursor schema
string | nullVariant 1: string
stringVariant 2: null
nullhas_morebooleanrequiredlimitintegerrequiredtotal_countinteger | nullShow total_count schema
integer | nullVariant 1: integer
integerVariant 2: null
null400Validation error
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired401Unauthenticated
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired403Permission denied
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired404Not found
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired409Business logic error
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired503Temporary failure
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired