> ## Documentation Index
> Fetch the complete documentation index at: https://docs.natural.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python.
> When operating Natural directly for a user, use the payments MCP at `https://mcp.natural.com`.
> When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> Use REST only for unsupported languages or when the user explicitly requests raw HTTP.
> Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it.
> For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer.
> REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code.

# Overview

> Review and respond to card payment chargebacks

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.

| Resource | Path | Holds |
| - | - | - |
| `chargeback` | `GET /chargebacks/{chargebackId}` | Amount, fee, reason, status, deadline, links to the payment |
| `chargebackEvidence` | `GET /chargebacks/{chargebackId}/evidence` | Your saved response, attached files, `version` |

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

| Status | Meaning | Disputed amount |
| - | - | - |
| `needsResponse` | A response or acceptance is available | Withheld |
| `submitted` | Natural accepted the response for delivery | Withheld |
| `underReview` | The provider acknowledged the submitted response | Withheld |
| `accepted` | You accepted the case | Not returned |
| `expired` | The response window ended | Not returned |
| `won` | The provider reported a win | Returned |
| `lost` | The provider reported a loss | Not returned |

`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](/guides/concepts/transactions#chargebacks).

## 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.

| Value | Meaning |
| - | - |
| `cardholderWithdrew` | The cardholder withdrew the dispute |
| `authorizedPurchase` | The purchase was made by the rightful cardholder |
| `alreadyRefunded` | The cardholder was refunded |
| `receivedProduct` | The cardholder received the product or service |
| `other` | Another reason, explained in `explanation` |

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.

| Purpose | What the file should show |
| - | - |
| `cardholderCommunications` | Emails, messages, or chats showing purchase participation or customer satisfaction |
| `receipt` | Receipt showing the amount, date and payment details |
| `authorizationProof` | A record showing the network approved this charge, including date and amount |
| `duplicatePaymentReceipt` | Receipt for the other charge the cardholder says was duplicated |
| `fulfillmentProof` | Carrier tracking, access or download records, or a service record showing what the customer bought and when you fulfilled it |
| `productDescription` | Product or service description shown to the customer before purchase |
| `cancellationPolicy` | Cancellation policy shown to the customer at purchase |
| `refundProof` | Refund record showing amount, date and return to the original payment method |
| `refundPolicy` | Refund policy shown to the customer at purchase |
| `disputeWithdrawal` | Written confirmation from the cardholder that they withdrew the dispute |
| `otherEvidence` | Any other document that supports your response |

## Recommended purposes

`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.

| Reason category | Recommended purposes |
| - | - |
| `fraud` | `cardholderCommunications`, `receipt`, `otherEvidence` |
| `authorization` | `authorizationProof`, `cardholderCommunications` |
| `duplicate` | `duplicatePaymentReceipt`, `cardholderCommunications` |
| `processingError` | `receipt`, `cardholderCommunications` |
| `notReceived` | `fulfillmentProof`, `cardholderCommunications` |
| `unacceptableOrCanceled` | `productDescription`, `cancellationPolicy`, `cardholderCommunications` |
| `creditNotProcessed` | `refundProof`, `refundPolicy`, `cardholderCommunications` |
| `unknown` | `otherEvidence`, `cardholderCommunications` |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.