Skip to main content
A chargeback (cbk_*) is a challenge to a card payment you received. It is separate from disputes you file about other transactions.

​
Two resources

A case has two resources. List cases with GET /chargebacks. Both reads require chargebacks.read. The case links to its card payment, payment intent, and receiving customer.

​
Respond to a case

  1. Read the evidence and note its version.
  2. Upload a file with POST /chargebacks/{chargebackId}/files using multipart form data.
  3. Save evidence and attach uploaded file IDs with PATCH /chargebacks/{chargebackId}/evidence.
  4. Preview the PDF with GET /chargebacks/{chargebackId}/evidence/preview. The preview shows your evidence only and leaves out Natural’s recorded records, which are added at submit.
  5. Submit with POST /chargebacks/{chargebackId}/submit using the version you reviewed.
Saving evidence does not submit it. Uploading a file does not change the case until you attach it. Submitted evidence is frozen. Every save that changes evidence advances the version. Send the current version on each save and on submit. A stale version returns 409. Read the evidence again before you retry. Use chargebacks.respond to save evidence, upload files, submit, or accept a case. It includes chargebacks.read. The preview requires only chargebacks.read.

​
Accept a case

Use POST /chargebacks/{chargebackId}/accept when you choose not to contest the case. It takes no body. This is a separate action from submitting evidence.

​
One deadline

responseDueAt is the deadline to submit evidence or accept the case. Natural enforces it. After it passes the case reads as expired and takes no response.

​
Status

submittedAt is null until submission. Accepted and expired cases do not imply a provider loss. A withheld amount is held back from your available balance. The hold can post shortly after the case is created.

​
Wallet debit

Natural debits a case’s disputed amount from your wallet and records it as a chargeback transaction.

​
Fee

fee is Natural’s fee for the case. It is billed once, when the case opens, so chargeback.created already carries it. It can be billed before the disputed amount is withheld, and it isn’t refunded if you win. fee is null when no fee applies or the fee was voided.

​
Response reasons

responseReason says why you contest the case. Refunds issued after the chargeback date do not count for alreadyRefunded. Refunds sent to a different payment method cannot be traced by the issuer.

​
File purposes

Each attached file carries one or more purposes. The purpose tells the reviewer what the file shows. recommendedPurposes on the evidence resource lists the purposes Natural recommends for the case. It is empty once the case can no longer be edited. The list follows the reason category and your response reason. A response reason of alreadyRefunded recommends refundProof instead. A response reason of cardholderWithdrew recommends disputeWithdrawal instead. cardholderCommunications is always recommended.

​
Required at submit

Submit needs these fields.
  • responseReason
  • productType
  • explanation
  • productDescription, unless the payment has a recorded sale description or line items
A submit with a missing field returns chargeback_required_evidence_missing. No file is required.

​
What Natural adds

Natural builds the evidence packet from your saved evidence and its own records. You do not supply these.
  • The payment amount, date, and reference
  • Card, authorization, address verification, and 3-D Secure results
  • Device and network facts captured at checkout
  • Checkout acceptance and disclosures, when recorded
  • The receipt email address, when recorded
  • Sale description and line items from the payment intent
  • Refund records for the payment
  • Prior payments from the same card
  • Your merchant identity
Your explanation and productDescription go on the cover page. Attached files follow as exhibits in the order you attach them.

​
Retry and event behavior

Mutations require an Idempotency-Key. Repeating a completed operation with the same request returns the original response after current authorization is checked. A new operation with an old version is rejected. Chargeback events carry the chargeback resource. Evidence never travels in an event. Saving evidence emits no event. chargeback.updated covers submission, acknowledgment, acceptance, and expiry. chargeback.closed reports provider wins and losses.