Disputes
A dispute is a customer's formal objection to a payment, raised with their bank or payment provider rather than with you. While the case runs, the disputed amount is taken back from you through a chargeback. You can send evidence to contest the dispute, or accept it.
When a dispute arrives
- The customer's bank reverses the payment with the scheme, and the scheme debits Rootline.
- Rootline registers a dispute against the original payment and notifies you.
- Rootline settles the disputed amount against your available balance, on the same delay as refunds initiated and payments captured that day. It is reported as
chargeback.
If your available balance does not cover the disputed amount, it goes negative and later payments replenish it.
While the dispute is open, the payment cannot be refunded: refund requests are rejected asynchronously via the refund.schedule.failed webhook, and a refund that was already scheduled before the dispute arrived does not prevent the chargeback debit. See Refunds and disputes.
See the settlement report for the rows, and Introduction to reconciliation for what this means for your balance.
Deciding whether to defend
Accepting is a valid option. Accept when the claim is justified, or when the amount is small enough that gathering evidence costs more than the payment is worth. You do not need to do anything to accept.
Defend when you can address the claim the customer made. Start as soon as you are notified: defense windows are short, and a case can only be submitted once, so it needs to be complete when it goes out.
Defending a chargeback describes what evidence to send for each reason.
Dispute reasons
Every dispute has one reason. It tells you what the customer is claiming, which determines what evidence is worth sending. The scheme's own reason code is available alongside it.
| Reason | What the customer claims |
|---|---|
unauthorized_transaction | They did not make or approve the payment |
authorization_error | The payment was processed without a valid authorization |
billing_error | Duplicate charge, wrong amount, or a refund that never arrived |
item_not_received | The goods or service never arrived |
item_not_as_described | What arrived was defective or materially different from the offer |
subscription_canceled | They canceled before the billing date |
other | No usable reason was given |
After the decision
The customer's bank reviews the evidence and decides, usually after several weeks. Rootline submits the case and reports the result, but has no influence on the outcome, and neither does the scheme unless the case is escalated further. In practice the decision is final.
If you win, Rootline credits the amount back to your available balance, shown as chargeback_returned. If you lose, the debit stands. In rare cases the customer's bank raises the same dispute again after a return, which debits you a second time and appears as chargeback_reaffirmed.
Disputes on a platform
When a payment was split, the dispute is settled against the accounts that received it: your platform account first, then the client merchants who received splits. Partial disputes, and disputes where the settlement currency differs from the original, stay at platform level.
Rootline notifies you, the platform, and not your client merchant. That leaves three things with you:
- Deciding whether to defend. Your client merchant usually has the facts, but the decision and the deadline are yours.
- Collecting the evidence. You have the payment and checkout records, and your client merchant has proof of delivery, correspondence and their own terms. A complete defense usually needs both.
- Telling your client merchant. The debit reaches their balance and their settlement report either way.
Rootline communicates with you rather than directly with your client merchants, so it helps to plan how you pass a dispute on to them.
Testing
You can run dispute scenarios against your own integration in the staging environment, so you can check your webhook handling and your reconciliation before a real dispute arrives.
Before you start, add the dispute events to your webhook endpoint in the dashboard, under Developer, then Webhooks: dispute.created, dispute.updated, dispute.closed and fraud_notification.received.
Rootline offers the following test scenarios, which you provide in the description field of the /payments request. The scenario runs when the payment is captured.
| Description value | Test scenario |
|---|---|
test_chargeback | A chargeback is raised and the dispute stays open. |
test_chargeback_won | A chargeback is raised, your defense succeeds, and the amount is returned. |
test_chargeback_lost | A chargeback is raised, the amount is returned, then the bank raises the case again and the chargeback stands. |
test_fraud_notification | A fraud notification on its own, with no dispute behind it. |
The description has to hold the scenario value on its own. If it contains anything else, the payment is processed as usual and no scenario runs.
Webhooks arrive within seconds of the capture. The settlement report rows follow on the next report cycle, the same sequence as a live dispute.
One difference from a live dispute: reason.provider_reason_code returns the scenario value, because there is no scheme code behind it. reason.code still carries a real category, so you can branch on it exactly as you would in production.