Managing Disputes

Learn how to manage chargebacks and disputed transactions.

Disputes (also known as chargebacks) happen when cardholders protest charges on their credit card statements with their card issuers.

The dispute and it's 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.

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 and guide you through the appeals process.

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.

Refunding Disputed Payments

{
    "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.

To receive notifications about disputes, subscribe to Finix's 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.

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.

{
    "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 using the returned id.

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

{
    "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.