Managing Disputes

Learn what to do when a buyer reports a payment to their issuing bank.

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:

  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 .

Manage Dispute in Dashboard

The Disputes Dashboard is under Exceptions. From their you can review a list of every dispute, navigate into the details of the dispute, and then 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/vnd.json+api" \
    -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.

Dispute States and Next Steps

Whether you're managing disputes through the dashboard or API. The state of the Dispute details what steps to take to move the Dispute forward:

  • PENDING The default state of Disputes . Evidence needs to be uploaded to defend the dispute.
  • 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 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

Create Dispute evidence to upload your defense material. Use the id of the Dispute to create the evidence.

  • 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/DItDftgrrkhcyFLzZiUFxn6Y/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/test-file.png"'

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.

Copy
Copied
{
    "id" : "DF2ZnzNUCz4AAabE64Uehgkb",
    "created_at" : "2021-05-25T00:34:48.37Z",
    "updated_at" : "2021-05-25T00:45:00.52Z",
    "dispute" : "DItDftgrrkhcyFLzZiUFxn6Y",
    "state" : "SUCCEEDED",
    "tags" : {
      "file-extension" : ".pdf",
      "content-type" : "application/pdf",
      "file-name" : "test-file.pdf"
    },
    "_links" : {
      "self" : {
        "href" : "https://finix.sandbox-payments-api.com/disputes/DItDftgrrkhcyFLzZiUFxn6Y/evidence/DF2ZnzNUCz4AAabE64Uehgkb"
        }
      }
    }

There are four values available for evidence#state that details the status of the evidence upload:

  • PENDING: The evidence file has not yet been submitted to the processor. No further action is required.
  • SUCCEEDED: The evidence file has been successfully sent to the processor. No further action is required.
  • CANCELED: The evidence file upload was cancelled by the uploader.
  • FAILED: An issue occurred. Any of the following issues could have occurred:
    • There was an error in the system and the uploader should try uploading the evidence again.
    • There is an issue with the file and the user should retry and upload a different file.
    • There is an issue and the user should contact Finix Support.

Finix Dashboard

Use the Disputes tab to upload evidence from the Finix Dashboard. For more information, see Managing Disputes on the 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 seller.
  • 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 seller.

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.