Interpret chargebacks on payments

When a payment enters a chargeback process, the chargeback object reports the current status of the dispute and the recorded reason.

Use this information to update your internal controls, direct the operational analysis, and track the disputed payment.

When to use

Check the chargeback object to:

• identify disputed payments;
• track the current stage of the process;
• classify the reported reason;
• update customer service and reconciliation flows;
• direct the analysis to the responsible team.

How to interpret

Simplified example:

{
  "chargeback": {
    "status": "IN_DISPUTE",
    "reason": "COMMERCIAL_DISAGREEMENT"
  }
}

In this example:

• IN_DISPUTE: the chargeback is in dispute;
• COMMERCIAL_DISAGREEMENT: the reported reason is a commercial disagreement.

Chargeback status

The chargeback.status field can return:

Chargeback reasons

The chargeback.reason field can return:

Handle the chargeback in your integration

When the chargeback object is returned:

1. read chargeback.status;
2. store the exact value received;
3. update the payment status in your system;
4. use chargeback.reason to direct the analysis;
5. keep a history of the changes.

Also handle values not yet mapped by your application. In these cases, preserve the original value received to avoid processing failures.

Next steps

• See the payment events
• Configure Webhooks
• Understand refunds
• Learn more about chargebacks