List Disputes

Retrieve a list of Disputes.

For details on how to query endpoints using the available parameters, see Query Parameters.

Request
query Parameters
limit
integer

The numbers of items to return.

Example: limit=10
created_at.gte
string <date-time>

Filter where created_at is after the given date.

Example: created_at.gte=2022-09-27T11:21:23
created_at.lte
string <date-time>

Filter where created_at is before the given date.

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

Filter where updated_at is after the given date.

Example: updated_at.gte=2022-09-27T11:21:23
updated_at.lte
string <date-time>

Filter where updated_at is before the given date.

Example: updated_at.lte=2023-01-21T10:17:22
transfer_id
string

Filter by the ID of the Transfer that's being disputed.

Note: If included, all other filter parameters are ignored.

adjustment_transfer_id
string

Filter by the ID of the adjustment Transfer.

Note: If included, all other filter parameters are ignored.

amount
integer

Filter by an amount equal to the given value.

Example: amount=100
amount.gte
integer

Filter by an amount greater than or equal.

Example: amount.gte=100
amount.gt
integer

Filter by an amount greater than.

Example: amount.gt=100
amount.lt
integer

Filter by an amount less than.

Example: amount.lt=100
state
string

Filter by the state of the Dispute.

response_state
string

Filter by the response_state of the Dispute.

respond_by.lte
string

Filter where respond_by is before the given date.

respond_by.gte
string

Filter where respond_by is after the given date.

instrument_bin
string

Filter by the Bank Identification Number (BIN). The BIN is the first 6 digits of the masked account number.

instrument_brand_type
string

Filter by the card brand used.

merchant_identity_id
string

Filter by the ID of the Identity used by the Merchant.

merchant_identity_name
string

Filter by the name used by the Merchant.

merchant_identity_name.like
string

Filter by the name used by the Merchant. Use this when searching with only partial name values.

instrument_name
string

Filter by the name of the Payment Instrument.

instrument_type
string

Filter by Payment Instrument type.

merchant_id
string

Filter by the ID of the Merchant.

merchant_mid
string

Filter by the MID of the Merchant.

instrument_card_last4
string

Filter by the last 4 digits of the card used.

instrument_card_type
string

Filter by the card type.

instrument_fingerprint
string

Filter by the fingerprint of the Payment Instrument.

before_cursor
string

Returns every Dispute created before the cursor value.

tags.key
string

Filter by the tag's key. For more information, see Tags.

Example: tags.key=card_type
tags.value
string

Filter by the tag's value. For more information, see Tags.

Example: tags.value=business_card
header Parameters
Accept
string
Default: application/hal+json

Body Header

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 "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/json
{}

Fetch a Dispute

Retrieve the details of a previously created Dispute.

Request
path Parameters
dispute_id
required
string

ID of Dispute.

header Parameters
Accept
string
Default: application/hal+json
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 "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/json
{}

Update a Dispute

Update tags on Disputes.

Request
path Parameters
dispute_id
required
string

ID of Dispute.

header Parameters
Accept
string
Default: application/hal+json
Finix-Version
string
Default: 2018-01-01

Specify the API version of your request. For more details, see Versioning.

Example: 2022-02-01
Request Body schema: application/json
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. (For example, order_number: 25, item_type: produce, department: sales)
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/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.


 
header Parameters
Accept
string
 Default:  application/hal+json
 
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' \
    -H "Finix-Version: 2022-02-01" \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -F "file"="@/Users/john.smith/Downloads/evidence.png"
Response samples 
application/json
{}
List Dispute Evidence
Retrieve a list of dispute evidence for a Dispute.


For details on how to query endpoints using the available parameters, see Query Parameters.      


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.


 
 Example:  after_cursor=TRnasXQ5AmjsLnPMwnme7TL4
before_cursor
string
Return every resource created before the cursor value.


 
 Example:  before_cursor=TRnasXQ5AmjsLnPMwnme7TL4
header Parameters
Accept
string
 Default:  application/hal+json
 
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 "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Response samples 
application/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.


 
header Parameters
Accept
string
 Default:  application/hal+json
 
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 "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Response samples 
application/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.


 
header Parameters
Accept
string
 Default:  application/hal+json
 
Finix-Version
string
 Default:  2018-01-01
Specify the API version of your request. For more details, see Versioning.


 
 Example:  2022-02-01
Request Body schema: application/json
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.
(For example, order_number: 25, item_type: produce, department: sales)
    • 



 
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/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.


 
 Example:  after_cursor=TRnasXQ5AmjsLnPMwnme7TL4
before_cursor
string
Return every resource created before the cursor value.


 
 Example:  before_cursor=TRnasXQ5AmjsLnPMwnme7TL4
header Parameters
Accept
string
 Default:  application/hal+json
 
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 "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Response samples 
application/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.


 
header Parameters
Accept
string
 Default:  application/hal+json
 
Finix-Version
string
 Default:  2018-01-01
Specify the API version of your request. For more details, see Versioning.


 
 Example:  2022-02-01
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/json" \
    -u "USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e" \
    -d '
    {
        "note": "Submitting Dispute Evidence: Valid Reason"
    }'
Response samples 
application/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.


 
header Parameters
Accept
string
 Default:  application/hal+json
 
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/json" \
    -H "Finix-Version: 2022-02-01" \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
    {
        "note": "Accepting Dispute: Valid Reason"
    }'
Response samples 
application/json
{}
Download Dispute Evidence
Download a file uploaded as Dispute Evidence.


Note: The file extension included in output must match the extension of the original uploaded file.


Request 
path Parameters
dispute_id
required
string
ID of Dispute to download evidence from.


 
 Example:  DIpCy4sZTx6im6U1ofBBPzdM
evidence_id
required
string
ID of evidence to download.


 
 Example:  DFtiQ1LoNbjBTYiuuxju6tE2
header Parameters
Accept
string
 Default:  application/hal+json
 
Responses 
200
Example response


401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


406
Not Acceptable


get/disputes/{dispute_id}/evidence/{evidence_id}/download
Request samples 
curl "https://finix.sandbox-payments-api.com/disputes/DIpCy4sZTx6im6U1ofBBPzdM/evidence/DFtiQ1LoNbjBTYiuuxju6tE2/download" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  --output DFtiQ1LoNbjBTYiuuxju6tE2.png

Response samples 
application/octet-stream
{}