Managing Disputes

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

When an unauthorized charge gets reported, the issuing bank creates a dispute, which immediately reverses the payment, credits the cardholder, and pulls the money from Finix. Finix then debits the 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.

Finix enables Merchants to appeal disputes using Finix's API or the Disputes tab of the Finix Dashboard. When a dispute gets created, Finix will notify you of the dispute with a webhook and guide you through the appeals process.

  • Notifications about Disputes is only available through Finix's API and Webhooks. To receive notifications about Disputes , subscribe to Finix's Webhooks .
  • 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.

Dispute Lifecycle

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

  1. Cardholder protests a charge with their bank.
  2. Bank reverses the payment and debits funds from Finix.
  3. 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 .
  4. 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
  5. 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.
  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:
    • 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 .

Receiving a Dispute

When a Dispute gets created, you'll get notified with a webhook. The webhook contains the details of the disputed transfer, and the id of the Dispute resource Finix created to manage the chargeback.

Example Webhook

Copy
Copied
{
  "type": "created",
  "entity": "dispute",
  "occurred_at": "2022-08-02T23:37:11.18Z",
  "_embedded": {
    "disputes": [
      {
        "reason": "FRAUD",
        "amount": 888888,
        "created_at": "2022-08-02T23:38:09.39Z",
        "message": null,
        "tags": {
          "order_number": "21DFASJSAKAS"
        },
        "occurred_at": "2022-08-02T23:37:11.18Z",
        "dispute_details": {
          "arn": "123"
        },
        "transfer": "TRXDo4T3HGxQupRzRJnUP1w",
        "application": "AP3AB2itAWrrrPVS6spvrGYp",
        "updated_at": "2022-08-02T23:38:08.90Z",
        "identity": "IDsArLxCm9QGbi2QfhaFrTED",
        "action": null,
        "id": "DInHi1mdk1h1kgNf5zBagAir",
        "state": "PENDING",
        "respond_by": "2022-08-09T23:38:09.38Z"
      }
    ]
  }
}

Example Dispute

Copy
Copied
{
    "id": "DInHi1mdk1h1kgNf5zBagAir",
    "application": "AP3AB2itAWrrrPVS6spvrGYp",
    "tags": {
        "order_number": "21DFASJSAKAS"
    },
    "amount": 888888,
    "state": "PENDING",
    "transfer": "TRXDo4T3HGxQupRzRJnUP1w",
    "reason": "FRAUD",
    "message": null,
    "action": null,
    "identity": "IDsArLxCm9QGbi2QfhaFrTED",
    "created_at": "2022-08-02T23:38:09.39Z",
    "updated_at": "2022-08-02T23:38:08.90Z",
    "occurred_at": "2022-08-02T23:37:11.18Z",
    "respond_by": "2022-08-09T23:38:09.38Z",
    "dispute_details": {
        "arn": "123"
    },
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/disputes/DInHi1mdk1h1kgNf5zBagAir"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/AP3AB2itAWrrrPVS6spvrGYp"
        },
        "transfer": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRXDo4T3HGxQupRzRJnUP1w"
        },
        "evidence": {
            "href": "https://finix.sandbox-payments-api.com/disputes/DInHi1mdk1h1kgNf5zBagAir/evidence"
        },
        "adjustment_transfers": {
            "href": "https://finix.sandbox-payments-api.com/disputes/DInHi1mdk1h1kgNf5zBagAir/adjustment_transfers"
        }
    }
}

The state of the webhook and Dispute detail what steps to take to move the Dispute forward.:

  • PENDING The default state of Disputes . The issuing bank is reviewing the details of the transaction and accepting evidence.
  • WON The issuing bank has overturned the dispute and ruled in favor of the Merchant. The credit gets reversed, and Finix returns the dispute amount to the Merchant .
  • LOST : The issuing bank has upheld the dispute. The cardholder will keep the credit, and the dispute amount does not return to the Merchant .
  • INQUIRY : A rare state used by some networks. INQUIRY indicates the Dispute got created, but funds haven't moved.

The reason of the webhook and Dispute provides additional details regarding why the dispute got filed:

  • 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 Merchant didn't respond by the respond_by date, or the transaction got flagged for review due to the network's internal standards.
  • 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.

Disputes get created with a PENDING state. To appeal a dispute, upload the evidence you have that proves the transaction is legitimate to the Dispute resource created by Finix. respond_by details the date the Merchant needs to respond by before the issuing bank closes the dispute in favor of the cardholder.

Uploading Evidence

Finix API

To upload evidence to a Dispute, use the id (Starts withDIxxxx) included in the initialdispute-created` webhook event you received.

  • You can upload up to 8 files; the total size of the uploaded files combined cannot exceed 10 MB.
  • The file formats allowed include JPG, PNG, PDF, or TIFF.
  • Individual PNG and JPEG files can't exceed 50 KB; PDF and TIFF files can't exceed 1 MB.
Copy
Copied
curl https://finix.sandbox-payments-api.com/disputes/DIo8nsKVmvbNtSqab9937ATm/evidence \
    -H "Content-Type: multipart/form-data" \
    -H 'Finix-Version:2022-02-01' \
    -u  USpumes23XhzHwXqiy9bfX2B:c69d39e3-f9ff-4735-8c3e-abca86441906 \
    -F 'file=@"/Users/john.smith/Downloads/Finix-disputes-evidence.png"'

Example Response

Copy
Copied
{
  "id" : "DFw2ESCkZQR5TZKDwp6eYDEA",
  "tags" : {
    "file-extension" : ".png",
    "content-type" : "image/png",
    "file-name" : "Finix-disputes-evidence.png"
  },
  "dispute" : "DIo8nsKVmvbNtSqab9937ATm",
  "state" : "PENDING",
  "created_at" : "2022-08-03T01:09:07.77Z",
  "updated_at" : "2022-08-03T01:09:07.77Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/disputes/DIo8nsKVmvbNtSqab9937ATm/evidence/DFw2ESCkZQR5TZKDwp6eYDEA"
    }
  }
}

HTTP Request

POST https://finix.sandbox-payments-api.com/disputes/:DISPUTE_ID:/evidence

URL Parameters

Parameter Description
:DISPUTE_ID: The ID of the Dispute. Use the id you received in the initial dispute-received webhook that starts with DIXXXX.

Request Arguments

Field Type Description
file string, required The location of the file on your local system.

A successful upload will return a response with PENDING saved for state. If you run into any issues or get a different response, try uploading the file again or in another format.

Finix Dashboard

Use the Disputes tab to upload evidence from the Finix Dashboard.

Understanding the Dispute Decision

Finix forwards the uploaded evidence to the issuing bank, which reviews the file(s) and either requests more information or makes a decision. When a decision gets made, Finix will notify you with a webhook and update the Dispute with the issuing bank's decision:

  • WON : The issuing bank reviewed the evidence and found the transaction is legitimate and the dispute doesn't have enough merit. The credit gets reversed, and Finix will return the dispute amount to the merchant.
  • LOST : The issuing bank reviewed the evidence and found the dispute has merit and the transaction is not legitimate. The cardholder will keep the credit, and the charge does not return to the merchant.

The outcome from the issuing bank is final for all parties. You can’t overturn a lost dispute, and your customer can’t overturn a dispute decided in your favor.

If you have questions about the status of a Dispute, reach out to Finix Support.