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

List cases with `GET /chargebacks`. Read a case with `GET /chargebacks/{chargebackId}`. Both require `chargebacks.read`. The case links to its card payment, payment intent, and receiving customer.

## Prepare a response

Natural supplies recorded payment, authentication, delivery-channel, and refund facts. `evidenceGuidance` explains the applicable response choices and missing information. Supply facts and documents that Natural does not already hold. Customer evidence supplements recorded facts.

1. Read the case and its `version`.
2. Upload a file through `POST /chargebacks/{chargebackId}/files` using multipart form data.
3. Save evidence and associate uploaded file IDs through `PATCH /chargebacks/{chargebackId}`.
4. Preview the PDF through `POST /chargebacks/{chargebackId}/preview`.
5. Submit with `POST /chargebacks/{chargebackId}/submit` using the reviewed version.

Saving evidence does not submit it. Uploading an unattached file does not change the case. New uploads return verified filename and size metadata. Historical files can have null metadata because it was not previously stored.

Evidence changes advance the case version. A stale version returns 409. Read the case again before retrying. Submitted evidence is frozen.

Use `chargebacks.respond` to save evidence, upload files, submit, or accept a case. It includes `chargebacks.read`. PDF preview requires only `chargebacks.read`.

## Accept a case

Use `POST /chargebacks/{chargebackId}/accept` with the current version when you choose not to contest it. This is a separate action from submitting evidence.

## Status

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

`responseDueAt` is the response deadline. `submittedAt` is null until submission. Accepted and expired cases do not imply a provider loss.

## 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 contain the case resource without evidence or evidence guidance. `chargeback.updated` includes acceptance and expiry. `chargeback.closed` reports provider wins and losses.