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.