# List Disputes

Retrieve a list of Dispute resources.

## Endpoint: 
GET /disputes  
**Security:** BasicAuth

## Header parameters:

- `Finix-Version` (string)  
  Specify the API version of your request. For more details, see Versioning.  
  **Example:** "2022-02-01"

## Query parameters:

- `adjustment_transfer_id` (string)  
  Filter by the ID of the adjustment Transfer. Note: If included, all other filter parameters are ignored.

- `application_id` (string)  
  Filter by Application ID.  
  **Example:** "APc9vhYcPsRuTSpKD9KpMtPe"

- `amount` (integer)  
  Filter by an amount equal to the given value.  
  **Example:** 100

- `amount.gt` (integer)  
  Filter by an amount greater than.  
  **Example:** 100

- `amount.gte` (integer)  
  Filter by an amount greater than or equal.  
  **Example:** 100

- `amount.lt` (integer)  
  Filter by an amount less than.  
  **Example:** 100

- `amount.lte` (integer)  
  Filter by an amount less than or equal.  
  **Example:** 100

- `after_cursor` (string)  
  Return every resource created after the cursor value.

- `before_cursor` (string)  
  Return every resource created before the cursor value.

- `created_at.gte` (string)  
  Filter where created_at is after the given date.  
  **Example:** "2022-09-27T11:21:23"

- `created_at.lte` (string)  
  Filter where created_at is before the given date.  
  **Example:** "2026-09-27T11:21:23"

- `buyer_identity_first_name` (string)  
  Filter by buyer's first name.

- `buyer_identity_last_name` (string)  
  Filter by buyer's last name.

- `buyer_business_name` (string)  
  Filter by the business_name of the buyer's Identity.

- `buyer_doing_business_as` (string)  
  Filter by the doing_business_as of the buyer's Identity.

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

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

- `instrument_name` (string)  
  Filter by the name of the Payment Instrument.

- `instrument_type` (string)  
  Filter by Payment Instrument type.

- `limit` (integer)  
  The numbers of items to return.  
  **Example:** 10

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

- `merchant_id` (string)  
  Filter by the ID of the Merchant.

- `merchant_mid` (string)  
  Filter by the MID of the Merchant.

- `names` (string)  
  Filter by the name used by the Merchant, the buyer's first and last name, business_name, and doing_business_as used by Identities when role is BUYER.

- `names.like` (string)  
  Filter by the name used by the Merchant, the buyer's first and last name, business_name, and doing_business_as used by Identities when role is BUYER. Use this when searching with only partial values.

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

- `tags` (string)  
  Filter by the key or value of tags.

- `tags.like` (string)  
  Filter by the key or value of tags. Use this when searching with only partial values.

- `tags.key` (string)  
  Filter by the tag's key. For more information, see Tags.  
  **Example:** "card_type"

- `tags.value` (string)  
  Filter by the tag's value. For more information, see Tags.  
  **Example:** "business_card"

- `transfer_id` (string)  
  Filter by the ID of the Transfer that's being disputed. Note: If included, all other filter parameters are ignored.

- `state` (string)  
  Filter by the state of the Dispute.

- `updated_at.gte` (string)  
  Filter where updated_at is after the given date.  
  **Example:** "2022-09-27T11:21:23"

- `updated_at.lte` (string)  
  Filter where updated_at is before the given date.  
  **Example:** "2026-09-27T11:21:23"

## Response 200 fields (application/json):

- `page` (object)  
  Details the page that's returned.

- `page.limit` (integer)  
  The number of entries to return.

- `page.next_cursor` (string,null)  
  The cursor to use for the next page of results.

- `_embedded` (object)

- `_embedded.disputes` (array)

- `_embedded.disputes.id` (string)  
  The ID of the resource.

- `_embedded.disputes.created_at` (string)  
  Timestamp of when the object was created.

- `_embedded.disputes.updated_at` (string)  
  Timestamp of when the object was last updated.

- `_embedded.disputes.action` (string,null)  
  The next action required to move forward with the Dispute.

- `_embedded.disputes.amount` (integer,null)  
  The total amount of the Dispute (in cents).

- `_embedded.disputes.application` (string)  
  ID of the Application the resource was created under.

- `_embedded.disputes.dispute_details` (object)  
  Details about the Dispute received by the processor. Any data from the processor can get included.

- `_embedded.disputes.dispute_details.case_id` (string,null)  
  The case number the processor has given the Dispute in their internal database.

- `_embedded.disputes.dispute_details.pin_debit_adjustment_number` (string,null)  
  A number used by the processor to identify the funds that are getting disputed.

- `_embedded.disputes.dispute_details.reason_code` (string,null)  
  A code used by the processor and card networks to identify why the Dispute got filed.

- `_embedded.disputes.evidence_submitted` (string)  
  The status of the uploaded evidence after it has been submitted to the issuing bank.

Possible values are:  
- INQUIRY: Updated to this value if Dispute#state is INQUIRY at the time of submission.  
- CHARGEBACK: Updated to this value if Dispute#state is PENDING at the time of submission.  
- NONE: No evidence has been uploaded or submitted yet.  
- NOT_SUPPORTED: The processor or dispute type (Dispute#reason) does not support evidence submission.  
- UNKNOWN: Occurs if evidence details couldn't be successfully processed or retrieved.  
Enum: "INQUIRY", "CHARGEBACK", "NONE", "NOT_SUPPORTED", "UNKNOWN"

- `_embedded.disputes.identity` (string)  
  The ID of the seller's Identity resource.

- `_embedded.disputes.merchant` (string)  
  The ID of the seller's Merchant resource.

- `_embedded.disputes.message` (string,null)  
  Additional dispute details. This field is typically null.

- `_embedded.disputes.occurred_at` (string,null)  
  A timestamp of when the disputed Transfer was created.

- `_embedded.disputes.reason` (string)  
  The system-defined reason for the Dispute. Available values include:

- CLERICAL: An error occurred while processing the sale, or the cardholder has an issue with the transaction and refuses the goods.
- FRAUD: The cardholder claims they didn't approve or authorize the transaction. FRAUD is the primary reason disputes get created.
- INQUIRY: The issuing bank requests more information to determine if a transaction was legitimate.
- QUALITY: The cardholder has issues with the quality of the goods or services received. Reasons can include receiving damaged goods or a service that doesn't match what's promised.
- TECHNICAL: A technical issued caused the transaction to process funds incorrectly.
Enum: "CLERICAL", "FRAUD", "INQUIRY", "QUALITY", "TECHNICAL"

- `_embedded.disputes.respond_by` (string,null)  
  A timestamp of when the Merchant must respond to the Dispute.

- `_embedded.disputes.response_state` (string)  
  Details the state of the Dispute and what action the Merchant needs to take. Possible values are:

- NEEDS_RESPONSE: The Merchant needs to respond to the Dispute by the Dispute#respond_by timestamp.
- RESPONDED: The issuing bank has received the evidence and actively reviewing it.
- ACCEPTED: The Merchant has accepted the Dispute.
- NO_RESPONSE_ALLOWED: The final Dispute#response_state when a Dispute is either WON or LOST.
- UNKNOWN: Occurs when testing Disputes in the sandbox.
Enum: "NEEDS_RESPONSE", "RESPONDED", "ACCEPTED", "NO_RESPONSE_ALLOWED", "UNKNOWN"

- `_embedded.disputes.state` (string)  
  The current overall state of the Dispute.
 
Possible values include:

- INQUIRY: The Dispute is being reviewed by the buyer's issuing bank.
- PENDING: The default initial state of a Dispute.
- LOST: The Dispute is lost, and the cardholder keeps the credit.
- WON: The Dispute is won, the credit is reversed, and funds are returned to the Merchant.
For more details, see Dispute States.
Enum: "INQUIRY", "PENDING", "LOST", "WON"

- `_embedded.disputes.transfer` (string)  
  ID of the Transfer resource.
  **Example:** "TRxxxxxxxxxxxxxxxxxx"

- `_embedded.disputes.tags` (object,null)  
  Include up to 50 key: value pairs to annotate requests with custom metadata.

- `_embedded.disputes._links` (object)  
  For your convenience, every response includes several URLs which link to resources relevant to the request.

- `_embedded.disputes._links.adjustment_transfers` (object)

- `_embedded.disputes._links.application` (object)  
  Link to the Application the resource was created under.

- `_embedded.disputes._links.evidence` (object)

- `_embedded.disputes._links.self` (object)  
  Link to the resource that was used in the request.

- `_embedded.disputes._links.transfer` (object)  
  Link to the Transfers related to the Dispute.

- `_links` (object)

- `_links.self` (object)  
  Link to the resource that was used in the request.

- `_links.next` (object)  
  Link to the next page of entries.

## Response 401 fields (application/json):

- `total` (integer, required)  
  Total number of errors returned.

- `_embedded` (object, required)  
  Container for embedded error objects.

- `_embedded.errors` (array)  
  List of individual error objects.