List Disputes

Retrieve a list of Disputes.

Request
query Parameters
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
limit
integer

The numbers of items to return.

Example: limit=10
offset
integer

The number of items to skip before starting to collect the result set.

Example: offset=20
sort
string

Specify key to be used for sorting the collection.

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.

Responses
200

List of Disputes

Response Schema: application/hal+json
object

List of Dispute objects.

object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

object
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.json+api" \
  -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 to fetch.

Responses
200

Single Dispute object

Response Schema: application/hal+json
object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

action
string or null

The next action required to move forward with the Dispute.

amount
integer or null

The total amount of the Dispute (in cents).

application
string

The ID of the Application resource the Dispute was created under.

created_at
string <date-time>

Timestamp of when the object was created.

currency
string

ISO 4217 3 letter currency code.

Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYR" "BZD" "CAD" "CDF" "CHE" "CHF" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HRK" "HTG" "HUF" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRO" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLL" "SOS" "SRD" "SSP" "STD" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL"
object

Details about the Dispute recieved by the Processor. May be any type of data.

id
string

The ID of the Dispute resource.

identity
string

The ID of the Identity the Dispute was created under.

message
string or null

Message field that provides additional details. This field is typically null.

occurred_at
string or null <date-time>

Point in time when dispute occurred.

reason
string

The system-defined reason for the Dispute. Available values include:

  • INQUIRY
  • QUALITY
  • FRAUD

Enum: "CLERICAL" "FRAUD" "INQUIRY" "QUALITY" "TECHNICAL"
respond_by
string or null <date-time>

Point in time when dispute has to be resolved and the Merchant needs to respond by.

state
string

The current state of the Dispute.

Enum: "INQUIRY" "PENDING" "WON" "LOST" "ARBITRATION"
object

Key value pair for annotating custom meta data (e.g. order numbers).

transfer
string

ID of the Transfer resource.

updated_at
string <date-time>

Timestamp of when the object was last updated.

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.json+api" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/hal+json
{}

Upload Dispute Evidence

Upload dispute 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

Response Schema: application/hal+json
object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

created_at
string <date-time>

Timestamp of when the object was created.

dispute
string

The ID of the Dispute associated with the evidence.

id
string

The ID of the Dispute resource.

state
string

Result of the evidence uploaded.

  • PENDING: The evidence file has not yet been submitted to the Processor. No user action is required.
  • SUCCEEDED: The evidence file has been successfully sent to the Processor. No further user action is required.
  • CANCELED: The evidence file upload was not completed due to user action.
  • FAILED: An issue occurred. User action is required**. Any of the following issues could have occurred:
    • There was an error in the system and the user should retry uploading their evidence file.
    • There is an issue with the file and the user should retry uploading a different file.
    • There is an issue and the user should contact Support.
Enum: "PENDING" "SUCCEEDED" "CANCELED" "FAILED"
object

Key value pair for annotating custom meta data (e.g. order numbers).

updated_at
string <date-time>

Timestamp of when the object was last updated.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

post/disputes/{dispute_id}/evidence
Request samples 
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
after_cursor
string
Return every resource created after the cursor value.


 
before_cursor
string
Return every resource created before the cursor value.


 
limit
integer
The numbers of items to return.


 
 Example:  limit=10
Responses 
200
List of Evidence objects


Response Schema: application/hal+json
object
List of evidence created for a Dispute.


 
object
For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.


 
object
Details the page that's returned.


 
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.json+api" \
  -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


Response Schema: application/hal+json
object
For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.


 
created_at
string <date-time> 
Timestamp of when the object was created.


 
dispute
string
The ID of the Dispute associated with the evidence.


 
id
string
The ID of the Dispute resource.


 
state
string
Result of the evidence uploaded.


    

  • PENDING: The evidence file has not yet been submitted to the Processor. No user action is required.
    • 

  • SUCCEEDED: The evidence file has been successfully sent to the Processor. No further user action is required.
    • 

  • CANCELED: The evidence file upload was not completed due to user action.
    • 

  • FAILED: An issue occurred. User action is required**. Any of the following issues could have occurred:
      

    • There was an error in the system and the user should retry uploading their evidence file.
      • 

    • There is an issue with the file and the user should retry uploading a different file.
      • 

    • There is an issue and the user should contact Support.
      • 

    

    • 



 Enum: "PENDING" "SUCCEEDED" "CANCELED" "FAILED"  
object
Key value pair for annotating custom meta data (e.g. order numbers).


 
updated_at
string <date-time> 
Timestamp of when the object was last updated.


 
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.json+api" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

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
after_cursor
string
Return every resource created after the cursor value.


 
before_cursor
string
Return every resource created before the cursor value.


 
limit
integer
The numbers of items to return.


 
 Example:  limit=10
Responses 
200
List of adjustment_transfer objects


Response Schema: application/hal+json
object
List of adjustment Transfers created for a Dispute.


 
object
For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.


 
object
Details the page that's returned.


 
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.json+api" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Response samples 
application/hal+json
{}