Payment Reversal (Chargeback) Use Case

Sometimes a payment you already registered gets reversed: a direct debit bounces, a card payment is charged back, or a bank transfer is recalled. If the claim was fully paid, it auto-resolved when you credited it — and now the debt needs to come back to life.

The reversal is one call: debit the reversed amount back and set options.forceAmountCheck so the claim's status is recomputed from the resulting balance. This reactivates a resolved claim (clearing its resolution reason) in the same request.

Example:

Let's assume John Doe's 20-euro payment bounced two weeks after you registered it, and his claim claim1 is currently resolved. Send:

POST /v1/3d132b18-6b6f-4f7c-b464-6a8ee7ca5235/debit_claims HTTP/1.1
Host: api.receive-demo.com
Content-Type: application/json
Authorization: {{access_token}}

{
  "claim1": {
    "amount": 2000,
    "currency": "EUR",
    "originator": "CLIENT",
    "descriptionText": "Direct debit reversal ref TRX-20260710-001",
    "options": {
      "forceAmountCheck": true
    }
  }
}

The claim's balance is restored to 20 euros and its status returns to active, so collection resumes.

Why the flag matters: without options.forceAmountCheck, the debit is still accepted and the balance is restored — but the claim stays resolved. A resolved claim with a positive balance is invisible to collection activity, which means the reversed debt would silently never be worked. Always set the flag on payment reversals.

Notes:

You can also debit fees, either as a number or as named { "name", "amount" } entries — for example, to add a chargebackFee bucket for the costs the reversal caused you. A debit with an unknown fee name creates a new bucket.
The flag works in both directions: it recomputes the status from the resulting total, reactivating the claim when the total is positive and resolving it when the total is zero or less.
If the claim was still active (partial payment reversed), the same request works — the flag is simply a no-op on the status.

FAQ

How can I get an Access Token? You can get a token using the Authentication Use Case
The debtor's collection journey — does it continue where it left off? The claim becomes active and eligible for collection again. If the exact resumption behaviour matters for your communication cadence, discuss it with your onboarding contact.
Can I reverse only part of a payment? Yes — debit only the reversed amount. Debits are incremental, like credits.

FAQ

Related Pages