Developers › After the payment

Disputes

A dispute is a cardholder telling their own bank to take a payment back. The money leaves your balance while the case is decided, you answer it with evidence, and the card network decides. This page is honest about the part of that which is done by hand.

Verified 6 November 2026Explain this to your team →

View as Markdown

How a dispute reaches you

Disputes are handled by hand. A chargeback arrives here as an email from the bank with a case reference, and somebody at Secure Processing reads it and records it. It is worth knowing because it decides the timings below.

When that happens you get a dispute.created webhook, and an email with the deadline in the subject line goes to your account's owner, who cannot turn it off, and by default to everyone else on your team who can answer disputes. The dispute also appears in your dashboard under Disputes, and the payment it came from has disputed: true.

You cannot create a dispute yourself, and there is no POST /v1/disputes. A chargeback is something the card network asserted; a business declaring one about its own payment would be moving its own money into reserve and back out again.

An inquiry is not a chargeback

Sometimes the cardholder’s bank asks a question before taking anything — a retrieval request. Those arrive with a status beginning warning_, and no money is held. Answer it well and it may never become a chargeback.

If the network escalates it anyway, the same dispute moves from warning_needs_response to needs_response, the money is held at that moment, and you get a dispute.funds_withdrawn event. It is never a second dispute.

Status	What it means
warning_needs_response	An inquiry. Nothing has been taken. Answer it.
warning_under_review	Your answer to an inquiry is with the bank.
warning_closed	The inquiry ended. No money moved at any point.
needs_response	A chargeback. The amount is out of your balance and evidence is due.
under_review	Your evidence is with us and on its way to the bank.
won	The bank found for you. The held amount is back in your balance.
lost	The bank found for the cardholder. The money stays gone.

What happens to the money

Opening a chargeback moves the disputed amount out of your available balance and into a reserve. Winning moves it back; losing writes it off. Every step is a balance transaction you can see, and the ids are on the dispute object.

When	What moves	On your statement
The dispute is opened	The disputed amount leaves your available balance	a dispute line, negative
You win	The same amount comes back	a dispute_reversal line, positive
You lose	Nothing further — it left at the start	no extra line, by design
A handling fee is charged	The fee leaves your available balance	a dispute line: amount 0, fee positive (what we charged, as on a charge), net negative

🔴 Your available balance can go negative. A chargeback usually arrives weeks after the payment, by which time you have been paid out — so there is nothing left to take, and the balance goes below zero. That is not an error; it is the amount you owe us. No further payout is made until your takings bring it back above zero.

The amount in the ledger is in Belize dollars at the rate the payment was taken at, which is why the dispute object carries both amount (the payment's currency) and settlement_amount (BZD).

Answering it

Evidence uses Stripe’s field names, so a library or a habit you already have will fit. Fields merge — sending the shipping section does not erase the receipt you sent yesterday — and sending null clears one.

bash

curl https://api.secureprocessing.app/v1/disputes/dp_4fH7jK9mN2pQ5rT8vX1zA3bC \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "evidence": {
      "shipping_carrier": "DHL",
      "shipping_tracking_number": "CP123456789BZ",
      "product_description": "One dive mask, collected in store"
    }
  }'

The file fields — receipt, shipping_documentation, customer_communication and the rest — take a file_ id. Uploading a file is session-only, so attach documents from the dashboard: they are often invoices naming a customer or a signed delivery note, and an API key is a long-lived credential in an environment variable.

When you are ready, send it. You can do this in the same call:

bash

curl https://api.secureprocessing.app/v1/disputes/dp_4fH7jK9mN2pQ5rT8vX1zA3bC \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "submit": true }'

⚠️ Submission is final, and it does not mean the bank has it yet. There is no system at the bank to post a bundle to, so a person here forwards it. Submitting freezes the evidence — the bundle they read has to be the bundle your record shows — and you will hear the outcome when the bank answers, which is their timeline and not ours.

The deadline

evidence_details.due_by comes from the cardholder’s bank and cannot be extended. A dispute with no answer is lost by default, so this is the one field on the object worth alerting on.

We email the owner, and by default everyone else on your team who can answer disputes, three days before the deadline and again the day before. We stop there: a third email on the morning it expires would arrive too late to act on. After the deadline the reminders stop and a person here chases the bank instead.

Accepting one

If you are not going to contest a dispute, say so and we will stop asking:

bash

curl -X POST https://api.secureprocessing.app/v1/disputes/dp_4fH7jK9mN2pQ5rT8vX1zA3bC/close \
  -H "Authorization: Bearer sk_test_..."

The method is called close because that is what Stripe calls it, and it means the same thing: you accept the loss. It moves no money on its own and it does not mark the dispute lost — the network has not decided yet, and we will not debit you ahead of them. A chargeback becomes under_review, an inquiry warning_under_review, and no further evidence is accepted.

You can accept only while the dispute is waiting for your response. Once you have submitted evidence the case is already with the bank, and accepting answers 400 and changes nothing. If you decide to concede after submitting, email support with the dispute id and we will tell the bank.

Events

Event	When
dispute.created	A chargeback or an inquiry was raised. The deadline is in evidence_details.
dispute.funds_withdrawn	The amount left your available balance. An inquiry does not fire this.
dispute.updated	Evidence saved or submitted, you accepted, or an inquiry escalated.
dispute.funds_reinstated	You won and the money is back.
dispute.closed	The bank answered. status is won, lost, or warning_closed.

Fees

A lost chargeback may carry a handling fee, charged to your available balance as its own balance transaction. It is not automatic and it is not a percentage: somebody decides it, it is on the dispute as dispute_fee, and the reason is in outcome_note. There is never a fee on a dispute you won.