# Managing Disputes Disputes (also known as chargebacks) happen when cardholders [protest charges](#protested-charges) on their credit card statements with their card issuers. In this guide, you can learn how to manage chargebacks and disputed transactions. ## Overview The dispute and [it's lifecycle](#dispute-lifecycle) is represented by the `Dispute` object. You can manage disputes through the dashboard on the **Transactions > Disputes** page, or via API. For more information, see [Managing Disputes on the Dashboard](/guides/after-the-payment/disputes/managing-disputes#manage-dispute-with-the-dashboard). Preventing and handling disputes is critical to processing payments. Should your dispute ratio (or that of sellers on your platform) become excessive, card networks may monitor and ultimately disable your payment processing ability. Additionally, cardholders dispute transactions, you can no longer refund the transaction – that becomes part of the dispute process. Platforms must notify their sellers when they receive disputes. This can be through a dashboard notification, email, or however you choose. ## Protested Charges When a buyer believes they have been incorrectly charged and disputes the transaction with their issuing bank, the dispute process begins. The issuing bank immediately reverses the payment, and notifies Finix about the dispute. Then, Finix debits the relevant Merchant account for the entirety of the dispute amount. Often, disputes happen when customers see charges on their statements that they don't recognize or remember. Throughout the dispute process, the issuing bank offers opportunities for merchants to provide evidence that proves the charge is legitimate. ## Dispute Lifecycle When the Dispute is created, Finix will notify you with [a webhook](#manage-dispute-with-the-api) and guide you through the appeals process. ![Finix Disputes Lifecycle](/assets/disputes-lifecycle.7a823fdc7ebdf52c537a5446d66fb589a48a6b45e1ab4ea1b092312d21789718.28b10c14.svg) The exact process varies by card network, but generally, disputes follow this standard process: 1. Cardholder protests a charge with their bank. 2. Issuing bank reverses the payment and debits funds from Finix. 3. Finix creates a `Dispute` and debits the funds from the `Merchant` (via their next `Settlement`). 4. Finix notifies the `Merchant` of the `Dispute` with: 1. A dispute entry on the **Disputes** tab of the Finix Dashboard. 2. A webhook that gets sent to the configured endpoint URL 5. The `Merchant` can either: 1. Accept the dispute. If the dispute is accepted, the cardholder keeps the credit, and the dispute amount does **not** return to the merchant. 2. Appeal and provide evidence. 6. If the `Merchant` appeals, Finix requests evidence that shows the charge is valid. 7. After the `Merchant` uploads evidence to the `Dispute`, Finix forwards the file(s) to the issuing bank. 8. The issuing bank makes a decision based on the evidence provided: 1. If the dispute gets upheld, the cardholder keeps the credit, and the dispute amount does not return to the `Merchant` . 2. If the dispute gets overturned, the credit is reversed, and Finix returns the dispute amount to the `Merchant` . The `state` of the `dispute` details where the issuing bank is in making their decision. Use the `state` of the `dispute` to determine your next steps. For more info, see [Dispute States](/guides/after-the-payment/disputes/dispute-states). ### Refunding Disputed Payments Disputed transactions cannot be refunded or reversed. Attempts to refund or reverse dispute transactions will fail with `409` error messages. ```json Error Message Reversing a Disputed Transfer { "total": 1, "_embedded": { "errors": [ { "logref": "180636a5364866d0", "message": "Reversals and refunds on transactions with disputes are not allowed.", "code": "CONFLICT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/transfers" } } } ] } } ``` ## Manage Dispute with the Dashboard To manage disputes on the Finix Dashboard, navigate to **Exceptions > Disputes**. From here you can review a list of every reported dispute, review the details of the dispute, and upload evidence. For more information, see [Managing Disputes on the Dashboard](/guides/after-the-payment/disputes/managing-disputes#manage-dispute-with-the-dashboard). To receive notifications about disputes, [subscribe to Finix's Webhooks](/additional-resources/developers/webhooks). ## Manage Disputes via API You can manage dispute programmatically using Webhook events and the Finix API. Managing disputes with the API starts with [receiving the `Dispute` webhook](/guides/after-the-payment/disputes/managing-disputes#receiving-disputes). ### Receiving Disputes When a `Dispute` gets created, you'll receive a webhook event with an `entity: dispute` and `type: created`. The webhook includes the `Dispute` resource. ```json Dispute Webhook Example { "type": "created", "entity": "dispute", "occurred_at": "2022-01-27T07:43:03.48Z", "_embedded": { "disputes": [ { "id": "DIs7yQRkHDdMYhurzYz72SFk", "application": "APgPDQrLD52TYvqazjHJJchM", "tags": { "order_number": "21DFASJSAKAS" }, "amount": 888888, "state": "PENDING", "transfer": "TRoTrJ3kqNTFh1P2FJ7A36Ky", "reason": "FRAUD", "message": null, "action": null, "identity": "IDpYDM7J9n57q849o9E9yNrG", "created_at": "2022-01-27T07:43:03.74Z", "updated_at": "2022-01-27T07:43:03.48Z", "occurred_at": "2022-01-27T07:42:48.56Z", "respond_by": "2022-02-03T07:43:03.73Z", "dispute_details": { "arn": "123" } } ] } } ``` You can [query the `Dispute`](/api/disputes/getdispute) using the returned `id`. ```shell Fetching a Dispute curl https://finix.sandbox-payments-api.com/disputes/DIs7yQRkHDdMYhurzYz72SFk \ -H "Content-Type: application/json" \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e ``` ```json Dispute Resource { "id": "DIs7yQRkHDdMYhurzYz72SFk", "application": "APgPDQrLD52TYvqazjHJJchM", "tags": { "order_number": "21DFASJSAKAS" }, "amount": 888888, "state": "PENDING", "transfer": "TRoTrJ3kqNTFh1P2FJ7A36Ky", "reason": "FRAUD", "message": null, "action": null, "identity": "IDpYDM7J9n57q849o9E9yNrG", "created_at": "2022-01-27T07:43:03.74Z", "updated_at": "2022-01-27T07:43:03.48Z", "occurred_at": "2022-01-27T07:42:48.56Z", "respond_by": "2022-02-03T07:43:03.73Z", "dispute_details": { "arn": "123" }, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/disputes/DIs7yQRkHDdMYhurzYz72SFk" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "transfer": { "href": "https://finix.sandbox-payments-api.com/transfers/TRoTrJ3kqNTFh1P2FJ7A36Ky" }, "evidence": { "href": "https://finix.sandbox-payments-api.com/disputes/DIs7yQRkHDdMYhurzYz72SFk/evidence" }, "adjustment_transfers": { "href": "https://finix.sandbox-payments-api.com/disputes/DIs7yQRkHDdMYhurzYz72SFk/adjustment_transfers" } } } ``` Use the `state` of the [`Dispute` to determine your next steps](/guides/after-the-payment/disputes/dispute-states/).