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

# Refund a payment

> Return part or all of a payment.

Refund a completed [payment intent](/guides/concepts/payment-intents) and Natural returns the money to the originating card, funded from the merchant's wallet.

<Snippet file="shared/prerequisites.mdx" />

<Snippet file="shared/cents-note.mdx" />

## Create the refund

Create it with [`POST /refunds`](/api-reference/refunds/create-refund). Name the intent, and set `amountMinor` for a partial refund or omit it to refund everything still refundable.

<Snippet file="shared/instance-id-note.mdx" />

```bash cURL theme={null}
# NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
curl -X POST https://api.natural.com/refunds \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "X-Instance-ID: $(uuidgen)" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "paymentIntentId": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7",
        "amountMinor": 1000,
        "currency": "USD",
        "reason": "requested_by_customer"
      }
    }
  }'
```

## Watch the refund

Read it with [`GET /refunds/{refundId}`](/api-reference/refunds/get-refund). A finished refund reads `succeeded` or `processedAs`.

## When a refund is refused

* `refund_payment_not_refundable`: the intent has no succeeded card payment.
* `refund_amount_exceeds_refundable`: the amount is more than what remains.
* `refund_in_progress`: another refund of this payment is still pending. The error names it in `pendingRefundId`; wait for it to finish.
* `refund_chargeback_open`: the payer disputed the payment, so it cannot be refunded.
* `refund_funds_unavailable`: your wallet balance cannot cover the amount. Deposit funds and retry.

## List refunds

[`GET /refunds`](/api-reference/refunds/list-refunds) lists your refunds newest first. Filter by `paymentIntentId` to see every refund of one payment.

```bash cURL theme={null}
curl "https://api.natural.com/refunds?paymentIntentId=pmi_019d0a1b2c3d4e5f60718293a4b5c6d7" \
  -H "Authorization: Bearer $NATURAL_API_KEY"
```

<Snippet file="api-examples/refunds.list.response.mdx" />