List Disputes

Retrieve a list of Disputes.

Request
query Parameters
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 created_at is after the given date.

Example: created_at.gte=2022-09-27T11:21:23
created_at.lte
string

Filter where created_at is before the given date.

Example: created_at.lte=2022-09-27T11:21:23
updated_at.gte
string

Filter where updated_at is after the given date.

updated_at.lte
string

Filter where updated_at is before the given date.

tags.key
string

Filter by the key of a Tag.

tags.value
string

Filter by the value of a Tag.

Responses
200

List of Disputes

401

Authentication information is missing or invalid

403

Forbidden

406

Not Acceptable

get/disputes
Request samples
curl https://finix.sandbox-payments-api.com/disputes/ \
  -H "Content-Type: application/vnd.api+json" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/hal+json
{}

Fetch a Dispute

Retrieve the details of a previously created Dispute.

Request
path Parameters
dispute_id
required
string

ID of Dispute.

Request Body schema: application/json
tags
required
object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500.

(e.g., order number: 25, item_type: produce, department: sales, etc.)

Responses
200

Single Dispute object

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/disputes/{dispute_id}
Request samples
curl https://finix.sandbox-payments-api.com/disputes/DIs7yQRkHDdMYhurzYz72SFk \
  -H "Content-Type: application/vnd.api+json" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/hal+json
{}

Update a Dispute

Update tags on Disputes.

Request
path Parameters
dispute_id
required
string

ID of Dispute.

Request Body schema: application/json
tags
required
object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500.

(e.g., order number: 25, item_type: produce, department: sales, etc.)

Responses
200

Single Dispute object

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

put/disputes/{dispute_id}
Request samples
Response samples
application/hal+json
{}

Upload Files as Dispute Evidence

Upload a file as evidence for a Dispute.

  • You can upload up to 8 files; the total size of the uploaded files combined cannot exceed 10 MB.
  • The allowed file formats include JPG, PNG, PDF, or TIFF.
  • Individual PNG and JPEG files can't exceed 50 KB; PDF and TIFF files can't exceed 1 MB.
Request
path Parameters
dispute_id
required
string

ID of Dispute to mange evidence for.

Request Body schema: multipart/form-data
file
string <binary>

The binary contents of the file.

Responses
201

Single Evidence object

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

post/disputes/{dispute_id}/evidence
Request samples
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"
Response samples
application/hal+json
{}

List Dispute Evidence

Retrieve a list of dispute evidence for a Dispute.

Request
path Parameters
dispute_id
required
string

ID of Dispute to mange evidence for.

query Parameters
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 key of a Tag.

tags.value
string

Filter by the value of a Tag.

Responses
200

List of Evidence objects

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/disputes/{dispute_id}/evidence
Request samples
curl https://finix.sandbox-payments-api.com/disputes/DIs7yQRkHDdMYhurzYz72SFk/evidence \
  -H "Content-Type: application/vnd.api+json" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/hal+json
{}

Fetch Dispute Evidence

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.

Request
path Parameters
dispute_id
required
string

ID of Dispute to fetch evidence for.

evidence_id
required
string

ID of evidence to fetch.

Responses
200

Single Evidence object

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/disputes/{dispute_id}/evidence/{evidence_id}
Request samples
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
Response samples
application/hal+json
{}

Update Dispute Evidence

Update tags on Dispute evidence.

Request
path Parameters
dispute_id
required
string

ID of Dispute to fetch evidence for.

evidence_id
required
string

ID of evidence to fetch.

Request Body schema: application/json
tags
required
object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500.

(e.g., order number: 25, item_type: produce, department: sales, etc.)

Responses
200

Single Evidence object

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

put/disputes/{dispute_id}/evidence/{evidence_id}
Request samples
Response samples
application/hal+json
{}

Fetch Dispute Adjustment Transfers

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:

  • PLATFORM_CREDIT
  • MERCHANT_DEBIT
  • MERCHANT_CREDIT
  • PLATFORM_DEBIT

Request
path Parameters
dispute_id
required
string

ID of the Dispute resource.

query Parameters
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.

Responses
200

List of adjustment_transfer objects

401

Unauthorized

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/disputes/{dispute_id}/adjustment_transfers
Request samples
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
Response samples
application/hal+json
{}

Submit Dispute Evidence

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.

Request
path Parameters
dispute_id
required
string

ID of Dispute to move forward and submit evidence.

Request Body schema: application/json
note
required
string

Include a note or custom metadata to reference the Dispute

Responses
200

Single Dispute object

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

422

Error

post/disputes/{dispute_id}/submit
Request samples
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"
    }'
Response samples
application/hal+json
{}

Accept a Dispute

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

Request
path Parameters
dispute_id
required
string

ID of Dispute to move forward and submit evidence.

Request Body schema: application/json
note
required
string

Include a note or custom metadata to reference the Dispute.

Responses
200

Single Dispute object

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

422

Error

post/disputes/{dispute_id}/accept
Request samples
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"
    }'
Response samples
application/hal+json
{}