Managing Disputes

Learn how to manage chargebacks and disputed transactions.

A Dispute (also known as a chargeback) comes up when a cardholder protests a charge on their statement with the issuing bank.

The dispute and it's lifecycle is represented in the Dispute object.

You can manage disputes through the dashboard on the Exceptions > Disputes page or through the API. For more information, see Managing Disputes on the Dashboard.

To the best of your ability, you should make sure your sellers respond to disputes and defend themselves. If the dispute to payment ratio gets too high, you may be put on a dedicated dispute program with the networks. If dispute ratio continues to get worse, card networks may disable the Merchant or the whole platform. Additionally, when a Dispute gets created, the original transaction can't be refunded.

It's the responsibility of the platform to notify the relevant Merchant when a dispute comes in. This can take the form of a notification in the platform, an email from support, etc.

Protested Charges

When a buyer believes they have been incorrectly charged, they report the transaction to their issuing bank, this starts the dispute process. The payment is immediately reversed, and the issuer reports the dispute back to Finix. Finix then debits the seller's Merchant account for the entirety of the dispute amount.

Disputes usually come up when customers see a charge on their statement that they don’t recognize or don’t remember. Throughout the dispute's lifecycle, the issuing bank offers the Merchant opportunities to provide evidence and prove the charge is legitimate.

Dispute Lifecycle

When a dispute gets created, Finix will notify you of the dispute with a webhook and guide you through the appeals process.

Finix Disputes Lifecycle

Even though the process can change depending on the card network, the lifecycle of most disputes in Finix follows this standard pattern:

Cardholder protests a charge with their bank.
Bank reverses the payment and debits funds from Finix.
Finix creates a Dispute and debits the funds from the Merchant . Specifically, from the Merchant's next Settlement .
- An Adjustment Transfer also gets created to debit the Dispute amount from the Settlement .
Finix notifies the Merchant of the Dispute with:
- A dispute entry on the Disputes tab of the Finix Dashboard.
- A webhook that gets sent to the configured endpoint URL
The Merchant can:
- Accept the dispute. If the dispute is accepted, the cardholder keeps the credit, and the dispute amount does not return to the merchant.
- Appeal and provide evidence.
If the Merchant appeals, Finix requests evidence that shows the charge is valid.
After the Merchant uploads evidence to the Dispute , Finix forwards the file(s) to the issuing bank.
The issuing bank makes a decision based on the evidence provided:
- If the dispute gets upheld, the cardholder keeps the credit, and the dispute amount does not return to the Merchant .
- 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.

Please note, disputed transactions can't be refunded or reversed. Any attempts at refunding or reversing a disputed transactions returns a 409 CONFLICT error message.

Disputes - Prohibited Refund

Copy

Copied

{
    "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 in Dashboard

To manage disputes on the Finix Dashboard, click 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 get notified of new disputes, subscribe to Finix's Webhooks.

Manage Dispute with the 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 a Dispute

When a Dispute gets created, you'll receive a webhook event with an entity of dispute and type of created. The webhook includes the Dispute resource.

Example Webhook

Copy

Copied

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

Copy

Copied

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

A successful response returns 200 and the Dispute resource.

Copy

Copied

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