--- title: "List Disputes" method: GET path: "/disputes" tags: ["Disputes"] --- # List Disputes `GET /disputes` Retrieve a list of `Dispute` resources. ## Query parameters - `adjustment_transfer_id` string - `application_id` string - `amount` integer - `amount.gt` integer - `amount.gte` integer - `amount.lt` integer - `amount.lte` integer - `after_cursor` string - `before_cursor` string - `created_at.gte` string, date-time - `created_at.lte` string, date-time - `buyer_identity_first_name` string - `buyer_identity_last_name` string - `buyer_business_name` string - `buyer_doing_business_as` string - `instrument_bin` string - `instrument_brand_type` string - `instrument_card_last4` string - `instrument_card_type` string - `instrument_fingerprint` string - `instrument_name` string - `instrument_type` string - `limit` integer - `merchant_identity_id` string - `merchant_identity_name` string - `merchant_identity_name.like` string - `merchant_id` string - `merchant_mid` string - `names` string - `names.like` string - `response_state` string - `respond_by.lte` string - `respond_by.gte` string - `tags` string - `tags.like` string - `tags.key` string - `tags.value` string - `transfer_id` string - `state` string - `updated_at.gte` string, date-time - `updated_at.lte` string, date-time ## Headers - `Finix-Version` string ## Response `200` List of `Dispute` resources - object - `page` Page — Details the page that's returned. - `limit` integer — The number of entries to return. - `next_cursor` string, nullable — The cursor to use for the next page of results. - `_embedded` object - `disputes` Dispute[] - `id` string — The ID of the resource. - `created_at` string, date-time — Timestamp of when the object was created. - `updated_at` string, date-time — Timestamp of when the object was last updated. - `action` string, nullable — The next `action` required to move forward with the `Dispute`. - `amount` integer, nullable — The total amount of the `Dispute` (in cents). - `application` string — ID of the `Application` the resource was created under. - `dispute_details` object — Details about the `Dispute` received by the processor. Any data from the processor can get included. - `case_id` string, nullable — The case number the processor has given the `Dispute` in their internal database. - `pin_debit_adjustment_number` string, nullable — A number used by the processor to identify the funds that are getting disputed. - `reason_code` string, nullable — A code used by the processor and card networks to identify why the `Dispute` got filed. - `evidence_submitted` 'INQUIRY' | 'CHARGEBACK' | 'NONE' | 'NOT_SUPPORTED' | 'UNKNOWN' — The status of the uploaded evidence after it has been submitted to the issuing bank. This field reflects how the `Dispute` is moving forward following the [submission of dispute evidence](/api/disputes/submitdisputeevidence). For more information on challenging a `Dispute`, see [Responding to Disputes](/guides/after-the-payment/disputes/responding-to-disputes). 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. - `identity` string — The ID of the seller's `Identity` resource. This is the `Identity` resource that was used to create the seller's `Merchant`. - `merchant` string — The ID of the seller's `Merchant` resource. This is the `Merchant` account the `Dispute` was filed against. - `message` string, nullable — Additional dispute details. This field is typically `null`. - `occurred_at` string, date-time, nullable — A timestamp of when the disputed `Transfer` was created. - `reason` 'CLERICAL' | 'FRAUD' | 'INQUIRY' | 'QUALITY' | 'TECHNICAL' — 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. - `respond_by` string, date-time, nullable — A timestamp of when the `Merchant` must respond to the `Dispute`. - `response_state` 'NEEDS_RESPONSE' | 'RESPONDED' | 'ACCEPTED' | 'NO_RESPONSE_ALLOWED' | 'UNKNOWN' — 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. For details on how to respond to a `Dispute`, see [Responding to Disputes](/guides/after-the-payment/disputes/responding-to-disputes). - `RESPONDED`: The issuing bank has received the evidence and actively reviewing it. No action needed from the `Merchant`. - `ACCEPTED`: The `Merchant` has accepted the `Dispute`. When a `Dispute` is accepted, you concede that the `Dispute` is not worth challenging or representing. For details on how to accept a `Dispute`, see [Accepting a Dispute](/guides/after-the-payment/disputes/accepting-disputes/). - `NO_RESPONSE_ALLOWED`: The final `Dispute#response_state` when a `Dispute` is either `WON` or `LOST`. - `UNKNOWN`: Occurs when testing `Disputes` in the sandbox on the `DUMMY_V1` processor or in production on the `VANTIV_V1` processor. - `state` 'INQUIRY' | 'PENDING' | 'LOST' | 'WON' — The current overall state of the `Dispute`. Disputes are initially created with a `PENDING` state. The decision of the issuing bank is final for all parties. Possible values include: - `INQUIRY`: The `Dispute` is being reviewed by the buyer's issuing bank. No changes can be made while in this state. If a `Dispute` reaches this state, the bank is requesting additional information from the seller to prove the transaction was legitimate. - `PENDING`: The default initial state of a `Dispute`. It also acts as a transitional state after an accept request is submitted. The state will eventually change based on the transaction type: - For a dispute on a **sale**: Changes to `LOST` when accepted. - For a dispute on a **refund**: Changes to `WON` when accepted. - `LOST`: The `Dispute` is lost, and the cardholder keeps the credit. No further changes can be made. - `WON`: The `Dispute` is won, the credit is reversed, and funds are returned to the `Merchant`. No further changes can be made. For more details, see [Dispute States](/guides/after-the-payment/disputes/dispute-states). - `transfer` string — ID of the `Transfer` resource. - `tags` Tags, nullable — 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`) - `_links` 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. - `adjustment_transfers` object - `href` string - `application` object — Link to the `Application` the resource was created under. - `href` string - `evidence` object - `href` string - `self` object — Link to the resource that was used in the request. - `href` string - `transfer` object — Link to the `Transfers` realted to the `Dispute`. - `href` string - `_links` object - `self` Self — Link to the resource that was used in the request. - `href` string - `next` Next — Link to the next page of entries. - `href` string ## Other responses - `401` — Unauthorized. Authentication is required and has failed or has not been provided. - `403` — Forbidden. The client is authenticated but does not have permission to access the resource. - `406` — Not Acceptable. The server could not accept the submitted request. Confirm how the request was formatted and submitted. - `422` — Unprocessable Entity. The syntax of the request content was correct, but the server was unable to process the contained instructions. --- [API](https://skmtc.net/finix/apis/finix-api-reference.md) · [All operations](https://skmtc.net/finix/apis/finix-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/finix/finix-api-reference/versions/5426f6f99c52/schema)