GET /disputes
GET /disputes/{id}
POST /disputes/{id}/evidence
GET /disputes/{id}/evidence
GET /disputes/{dispute_id}/evidence/{evidence_id}
GET /disputes/{dispute_id}/adjustment_transfers
Disputes
, also known as chargebacks, represent any customer-disputed charges. A core part of the dispute lifecycle is the ability for a Merchant
to upload Dispute
evidence that supports their side of the Dispute
.
Related Guides: Managing Disputes
Retrieve a list of Disputes
.
sort | string Specify key to be used for sorting the collection. |
offset | integer The number of items to skip before starting to collect the result set. Example: offset=20 |
limit | integer The numbers of items to return. Example: limit=10 |
created_at.gte | string Filter where Example: created_at.gte=2022-09-27T11:21:23 |
created_at.lte | string Filter where Example: created_at.lte=2022-09-27T11:21:23 |
updated_at.gte | string Filter where |
updated_at.lte | string Filter where |
tags.key | string Filter by the |
tags.value | string Filter by the value of a |
List of Disputes
Authentication information is missing or invalid
Forbidden
Not Acceptable
curl https://finix.sandbox-payments-api.com/disputes/ \ -H "Content-Type: application/vnd.api+json" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
{- "_embedded": {
- "disputes": [
- {
- "id": "DIb72obRhTmPdMG1VxDKFLrb",
- "created_at": "2022-07-14T19:40:06.52Z",
- "updated_at": "2022-07-14T19:40:06.11Z",
- "action": null,
- "amount": 888888,
- "application": "APgPDQrLD52TYvqazjHJJchM",
- "dispute_details": {
- "arn": "123"
}, - "identity": "IDuqZpDw28f2KK6YuDk4jNLg",
- "message": null,
- "occurred_at": "2022-07-14T19:39:00.77Z",
- "reason": "FRAUD",
- "respond_by": "2022-07-21T19:40:06.51Z",
- "state": "PENDING",
- "tags": {
- "test": "sale"
}, - "transfer": "TRkhvS4GfMKxaHyBBdkPSx6g",
- "_links": {
- "application": {
}, - "evidence": {
}, - "adjustment_transfers": {
}
}
}, - {
- "id": "DIuk8T4ayQdmxewz8EDLHe49",
- "created_at": "2022-06-15T16:14:03.95Z",
- "updated_at": "2022-06-15T16:14:03.64Z",
- "action": null,
- "amount": 888888,
- "application": "APgPDQrLD52TYvqazjHJJchM",
- "dispute_details": {
- "arn": "123"
}, - "identity": "IDpYDM7J9n57q849o9E9yNrG",
- "message": null,
- "occurred_at": "2022-06-15T16:13:04.09Z",
- "reason": "FRAUD",
- "respond_by": "2022-06-22T16:14:03.94Z",
- "state": "PENDING",
- "tags": {
- "order_number": "21DFASJSAKAS"
}, - "transfer": "TR27JnLR2pKDXjVVcGBKrjwU",
- "_links": {
- "application": {
}, - "evidence": {
}, - "adjustment_transfers": {
}
}
}, - {
- "id": "DIs7yQRkHDdMYhurzYz72SFk",
- "created_at": "2022-01-27T07:43:03.74Z",
- "updated_at": "2022-09-16T22:21:54.75Z",
- "action": null,
- "amount": 888888,
- "application": "APgPDQrLD52TYvqazjHJJchM",
- "dispute_details": {
- "arn": "123"
}, - "identity": "IDpYDM7J9n57q849o9E9yNrG",
- "message": null,
- "occurred_at": "2022-01-27T07:42:48.56Z",
- "reason": "FRAUD",
- "respond_by": "2022-02-03T07:43:03.73Z",
- "state": "WON",
- "tags": {
- "order_number": "21DFASJSAKAS"
}, - "transfer": "TRoTrJ3kqNTFh1P2FJ7A36Ky",
- "_links": {
- "application": {
}, - "evidence": {
}, - "adjustment_transfers": {
}
}
}
]
}, - "_links": {
}, - "page": {
- "offset": 0,
- "limit": 20,
- "count": 3
}
}
Retrieve the details of a previously created Dispute
.
Single Dispute object
Authentication information is missing or invalid
Forbidden
Object does not exist
Not Acceptable
curl https://finix.sandbox-payments-api.com/disputes/DIs7yQRkHDdMYhurzYz72SFk \ -H "Content-Type: application/vnd.api+json" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
{- "id": "DIs7yQRkHDdMYhurzYz72SFk",
- "created_at": "2022-01-27T07:43:03.74Z",
- "updated_at": "2022-09-16T22:21:54.75Z",
- "action": null,
- "amount": 888888,
- "application": "APgPDQrLD52TYvqazjHJJchM",
- "dispute_details": {
- "arn": "123"
}, - "evidence_submitted": "CHARGEBACK",
- "identity": "IDpYDM7J9n57q849o9E9yNrG",
- "message": null,
- "occurred_at": "2022-01-27T07:42:48.56Z",
- "reason": "FRAUD",
- "respond_by": "2022-02-03T07:43:03.73Z",
- "response_state": "ACCEPTED",
- "state": "WON",
- "tags": {
- "order_number": "41BFASJSAKAS"
}, - "transfer": "TRoTrJ3kqNTFh1P2FJ7A36Ky",
- "_links": {
- "application": {
}, - "evidence": {
}, - "adjustment_transfers": {
}
}
}
Update tags
on Disputes
.
Single Dispute object
Authentication information is missing or invalid
Forbidden
Object does not exist
Not Acceptable
{- "id": "DIs7yQRkHDdMYhurzYz72SFk",
- "created_at": "2022-01-27T07:43:03.74Z",
- "updated_at": "2022-09-16T22:21:54.75Z",
- "action": null,
- "amount": 888888,
- "application": "APgPDQrLD52TYvqazjHJJchM",
- "dispute_details": {
- "arn": "123"
}, - "evidence_submitted": "CHARGEBACK",
- "identity": "IDpYDM7J9n57q849o9E9yNrG",
- "message": null,
- "occurred_at": "2022-01-27T07:42:48.56Z",
- "reason": "FRAUD",
- "respond_by": "2022-02-03T07:43:03.73Z",
- "response_state": "ACCEPTED",
- "state": "WON",
- "tags": {
- "order_number": "41BFASJSAKAS"
}, - "transfer": "TRoTrJ3kqNTFh1P2FJ7A36Ky",
- "_links": {
- "application": {
}, - "evidence": {
}, - "adjustment_transfers": {
}
}
}
Upload a file as evidence for a Dispute
.
Single Evidence object
Authentication information is missing or invalid
Forbidden
Object does not exist
Not Acceptable
curl https://finix.sandbox-payments-api.com/disputes/DIs7yQRkHDdMYhurzYz72SFk/evidence \ -H 'Content-Type: multipart/form-data' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -F "file"="@/Users/john.smith/Downloads/evidence.png"
{- "id": "DF58kdVTa5eMQUjcXH2F7DH4",
- "created_at": "2022-08-15T21:37:04.41Z",
- "updated_at": "2022-08-15T21:45:00.74Z",
- "dispute": "DIs7yQRkHDdMYhurzYz72SFk",
- "state": "SUCCEEDED",
- "tags": {
- "file-extension": ".png",
- "content-type": "image/png",
- "file-name": "test_file.png"
}, - "_links": {
}
}
Retrieve a list of dispute evidence for a Dispute
.
limit | integer The numbers of items to return. Example: limit=10 |
after_cursor | string Return every resource created after the cursor value. |
before_cursor | string Return every resource created before the cursor value. |
tags.key | string Filter by the |
tags.value | string Filter by the value of a |
List of Evidence objects
Authentication information is missing or invalid
Forbidden
Object does not exist
Not Acceptable
curl https://finix.sandbox-payments-api.com/disputes/DIs7yQRkHDdMYhurzYz72SFk/evidence \ -H "Content-Type: application/vnd.api+json" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
{- "_embedded": {
- "evidences": [
- {
- "id": "DFcVgoEuDeWn4eSvdZca8Hf",
- "created_at": "2022-10-06T20:22:54.93Z",
- "updated_at": "2022-10-06T20:30:00.63Z",
- "dispute": "DIs7yQRkHDdMYhurzYz72SFk",
- "state": "SUCCEEDED",
- "tags": {
- "file-extension": ".png",
- "content-type": "image/png",
- "file-name": "test_file.png"
}, - "_links": {
}
}, - {
- "id": "DFx3tddpTC568GjukRFGZpDp",
- "created_at": "2022-09-14T17:36:33.84Z",
- "updated_at": "2022-09-14T17:45:00.51Z",
- "dispute": "DIs7yQRkHDdMYhurzYz72SFk",
- "state": "SUCCEEDED",
- "tags": {
- "file-extension": ".png",
- "content-type": "image/png",
- "file-name": "test_file.png"
}, - "_links": {
}
}
]
}, - "_links": {
}, - "page": {
- "offset": 0,
- "limit": 20,
- "count": 1169
}
}
Fetch evidence uploaded for a Dispute
.
If you don't have the Finix Dashboard available, you can fetch the evidence to review the status
of the upload to confirm the evidence got sent to the processor.
Single Evidence object
Authentication information is missing or invalid
Forbidden
Object does not exist
Not Acceptable
curl https://finix.sandbox-payments-api.com/disputes/DIs7yQRkHDdMYhurzYz72SFk/evidence/DF58kdVTa5eMQUjcXH2F7DH4 \ -H "Content-Type: application/vnd.api+json" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
{- "id": "DF58kdVTa5eMQUjcXH2F7DH4",
- "created_at": "2022-08-15T21:37:04.41Z",
- "updated_at": "2022-08-15T21:45:00.74Z",
- "dispute": "DIs7yQRkHDdMYhurzYz72SFk",
- "state": "SUCCEEDED",
- "tags": {
- "file-extension": ".png",
- "content-type": "image/png",
- "file-name": "test_file.png"
}, - "_links": {
}
}
Update tags on Dispute
evidence.
Single Evidence object
Authentication information is missing or invalid
Forbidden
Object does not exist
Not Acceptable
{- "id": "DF58kdVTa5eMQUjcXH2F7DH4",
- "created_at": "2022-08-15T21:37:04.41Z",
- "updated_at": "2022-08-15T21:45:00.74Z",
- "dispute": "DIs7yQRkHDdMYhurzYz72SFk",
- "state": "SUCCEEDED",
- "tags": {
- "order_number": "41BFASJSAKAS"
}, - "_links": {
}
}
List the adjustment Transfers
for a Dispute
. Depending on the stage of the Dispute
, different adjustment Transfer
subtypes can be applied.
There are four available subtypes for adjustment Transfers
in Disputes
:
List of adjustment_transfer objects
Unauthorized
Forbidden
Object does not exist
Not Acceptable
curl https://finix.sandbox-payments-api.com/disputes/DIs7yQRkHDdMYhurzYz72SFk/adjustment_transfers \ -H "Content-Type: application/vnd.api+json" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
{- "_embedded": {
- "transfers": [
- {
- "id": "TRrqiR7x5zwUPV5SpPSbKH8B",
- "created_at": "2022-01-27T07:43:03.94Z",
- "updated_at": "2022-01-27T07:43:03.48Z",
- "additional_buyer_charges": null,
- "additional_healthcare_data": null,
- "address_verification": null,
- "amount": 888888,
- "amount_requested": 888888,
- "application": "APgPDQrLD52TYvqazjHJJchM",
- "currency": "USD",
- "destination": null,
- "externally_funded": "FALSE",
- "failure_code": null,
- "failure_message": null,
- "fee": 0,
- "idempotency_id": null,
- "merchant_identity": "IDddHpRqwf2VsH2XB1fmLfhM",
- "messages": [ ],
- "raw": null,
- "ready_to_settle_at": "2022-01-27T07:43:03.91Z",
- "security_code_verification": null,
- "source": null,
- "state": "SUCCEEDED",
- "statement_descriptor": null,
- "subtype": "PLATFORM_CREDIT",
- "tags": { },
- "trace_id": "c14d481c-60eb-4338-8331-9f34b3445710",
- "type": "DISPUTE",
- "_links": {
- "application": {
}, - "merchant_identity": {
}, - "payment_instruments": {
}, - "disputed_transfer": {
}, - "fee_profile": {
}
}
}, - {
- "id": "TRw6U5auHfgKfgT4APKgkh4f",
- "created_at": "2022-09-16T22:21:54.66Z",
- "updated_at": "2022-09-16T22:21:54.66Z",
- "additional_buyer_charges": null,
- "additional_healthcare_data": null,
- "address_verification": null,
- "amount": 888888,
- "amount_requested": 888888,
- "application": "APgPDQrLD52TYvqazjHJJchM",
- "currency": "USD",
- "destination": null,
- "externally_funded": "FALSE",
- "failure_code": null,
- "failure_message": null,
- "fee": 0,
- "idempotency_id": null,
- "merchant_identity": "IDpYDM7J9n57q849o9E9yNrG",
- "messages": [ ],
- "raw": null,
- "ready_to_settle_at": "2022-09-16T22:21:54.81Z",
- "security_code_verification": null,
- "source": "PIe2YvpcjvoVJ6PzoRPBK137",
- "state": "SUCCEEDED",
- "statement_descriptor": null,
- "subtype": "MERCHANT_CREDIT",
- "tags": { },
- "trace_id": "d5416d16-df58-4c9a-9759-076cb28800d5",
- "type": "DISPUTE",
- "_links": {
- "application": {
}, - "merchant_identity": {
}, - "payment_instruments": {
}, - "disputed_transfer": {
}, - "source": {
}, - "fee_profile": {
}
}
}
]
}, - "page": {
- "offset": 0,
- "limit": 20,
- "count": 4
}
}
You can manually submit evidence to the issuing bank to manually move a dispute forward. Use the /disputes/DISPUTE_ID/submit
endpoint to submit evidence. Making a POST request lets the issuing bank know the seller has completed submitting evidence and is prepared to move forward with the dispute.
Related guides: Responding to Disputes.
Single Dispute object
Authentication information is missing or invalid
Forbidden
Object does not exist
Not Acceptable
Error
curl https://finix.sandbox-payments-api.com/disputes/DIs7yQRkHDdMYhurzYz72SFk/submit \ -H 'Content-Type: application/vnd.json+api' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -d ' { "note": "Submitting Dispute Evidence: Valid Reason" }'
{- "id": "DIs7yQRkHDdMYhurzYz72SFk",
- "created_at": "2022-01-27T07:43:03.74Z",
- "updated_at": "2022-09-16T22:21:54.75Z",
- "action": null,
- "amount": 888888,
- "application": "APgPDQrLD52TYvqazjHJJchM",
- "dispute_details": {
- "arn": "123"
}, - "evidence_submitted": "CHARGEBACK",
- "identity": "IDpYDM7J9n57q849o9E9yNrG",
- "message": null,
- "occurred_at": "2022-01-27T07:42:48.56Z",
- "reason": "FRAUD",
- "respond_by": "2022-02-03T07:43:03.73Z",
- "response_state": "ACCEPTED",
- "state": "WON",
- "tags": {
- "order_number": "21DFASJSAKAS"
}, - "transfer": "TRoTrJ3kqNTFh1P2FJ7A36Ky",
- "_links": {
- "application": {
}, - "evidence": {
}, - "adjustment_transfers": {
}
}
}
You can accept a Dispute
to prevent a long (and potentially expensive) process. When you accept a Dispute
, you concede that the Dispute is not worth challenging or representing.
Related guides: Accepting a Dispute
Single Dispute object
Authentication information is missing or invalid
Forbidden
Object does not exist
Not Acceptable
Error
curl https://finix.sandbox-payments-api.com/disputes/DIs7yQRkHDdMYhurzYz72SFk/accept \ -H "Content-Type: application/vnd.json+api" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -d ' { "note": "Accepting Dispute: Valid Reason" }'
{- "id": "DIs7yQRkHDdMYhurzYz72SFk",
- "created_at": "2022-01-27T07:43:03.74Z",
- "updated_at": "2022-09-16T22:21:54.75Z",
- "action": null,
- "amount": 888888,
- "application": "APgPDQrLD52TYvqazjHJJchM",
- "dispute_details": {
- "arn": "123"
}, - "evidence_submitted": "CHARGEBACK",
- "identity": "IDpYDM7J9n57q849o9E9yNrG",
- "message": null,
- "occurred_at": "2022-01-27T07:42:48.56Z",
- "reason": "FRAUD",
- "respond_by": "2022-02-03T07:43:03.73Z",
- "response_state": "ACCEPTED",
- "state": "WON",
- "tags": {
- "order_number": "21DFASJSAKAS"
}, - "transfer": "TRoTrJ3kqNTFh1P2FJ7A36Ky",
- "_links": {
- "application": {
}, - "evidence": {
}, - "adjustment_transfers": {
}
}
}