Disputes

A dispute is a customer's challenge to one of your card payments, raised through their bank. The bank takes the money back from the payment through the card network: a chargeback. Each chargeback is one dispute, on the payment it challenges, and you are told of it by a dispute.created event.

The disputes API is read-only: List disputes and Retrieve a dispute. You respond to a dispute from the Merchant Dashboard; the platform's operations team take the case to the card network for you.

What a chargeback costs

When a dispute opens, these are taken from the funds due to you, even if that takes your balance below zero:

	Field
The amount disputed	amount	All of the payment, or part of it.
The chargeback cost	chargeback_cost	What the card provider charges for a chargeback. 0 when it charges nothing.
An admin fee	admin_fee	Only if your platform sets one for the payment method; 0 otherwise.

debited says what came off your balance in all. The fees on the original payment are not returned, however the dispute ends. The payment itself never changes: it stays succeeded, as it was paid.

If you take payments under a platform that bears its merchants' chargebacks, charged_to is platform and debited is 0: nothing comes off your balance. Otherwise charged_to is you.

How a dispute goes

open

under_review

won

lost

accepted

Press enter or space to select a node. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

open

under_review

won

lost

accepted

Press enter or space to select a node. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

How a dispute's status changes. Its states: open, under_review, won (final), lost (final), accepted (final).

1. open to under_review
2. open to won, lost or accepted
3. under_review to won, lost or accepted

Status	When
open	The chargeback has arrived, and the money in the table above was taken.
under_review	The operations team are working the case with the card network.
won	Decided for you, or the network reversed the chargeback. Final.
lost	Decided for the customer. Final.
accepted	You, or the operations team, accepted the chargeback without contesting it. Final.

A dispute can be decided, or accepted, from open or under_review. Once it is won, lost or accepted, closed says when, and it never changes again.

Responding

Respond from the Merchant Dashboard, under Disputes, where team members with the View permission see every dispute and those with Admin respond to them:

• Upload evidence: a PDF, JPEG or PNG of up to 10 MB each, such as a receipt, proof of delivery, or your correspondence with the customer, with a description if you like. Upload as many as the case needs. The operations team use it to answer the card network.
• Accept the dispute, with a reason, if you do not want to contest it: it closes accepted, and what was taken is not returned.

When the operations team need something particular, evidence_request says what, and you get dispute.updated. Evidence cannot be sent over the API.

Due dates

evidence_due_date is the last day to respond, a calendar date in your platform's time zone. It may be set after the dispute opens, or moved while it is worked; each change sends dispute.updated. The Merchant Dashboard flags a dispute due within two business days, and one past its date. Evidence can still be uploaded until the dispute is decided, but evidence sent after the due date may be too late to be used.

What winning returns

A dispute that is won returns the disputed amount to the funds due to you. The chargeback_cost is returned only if the card provider returns it: a won dispute's cost_returned shows whether it came back, and how much, and is 0 if it did not. The admin_fee, and the fees on the original payment, are not returned. A dispute that is lost or accepted returns nothing.

Listening for disputes

Subscribe a webhook endpoint to the three dispute events, and look the dispute up by its payment_intent to find the order:

Event	When
dispute.created	A chargeback arrived and its dispute opened.
dispute.updated	It went under_review, evidence was asked for, its due date was set or moved, or evidence was uploaded.
dispute.closed	It was decided: won, lost or accepted.

Each carries the dispute as GET /v1/disputes/{id} returns it. Deliveries can arrive more than once and out of order, so go by the dispute's status, not by the order events arrive in, and retrieve the dispute when in doubt.

Trying it in test mode

In test mode, a card payment of PHP 404.00 is charged back once it succeeds: see Test mode and test values.