> ## 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 card payment

> Return part or all of a card payment to the card that paid

Return part or all of a successful card payment to the card that paid.

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

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

<Note>
  Refunding for a customer? Pass their party ID as `customerPartyId` on each call. Your agent needs
  permission to act on their behalf.
</Note>

## Create the refund

[Create a refund](/api-reference/refunds/create-refund) with either `paymentIntentId` or `cardPaymentId`, not both. Set `amount` for a partial refund. Omit it to refund the remaining amount.

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

<CodeGroup>
  ```python Python theme={null}
  import uuid
  from naturalpay import Natural

  # Set NATURAL_API_KEY to your agent's API key.
  client = Natural(instance_id=str(uuid.uuid4()))

  refund = client.refunds.create(
      payment_intent_id="pmi_019d0a1b2c3d4e5f60718293a4b5c6d7",
      amount=1000,
      reason="requestedByPayer",
      idempotency_key=str(uuid.uuid4()),
  )
  ```

  ```typescript TypeScript theme={null}
  import Natural from "@naturalpay/sdk";

  // Set NATURAL_API_KEY to your agent's API key.
  const client = new Natural();
  const refund = await client.refunds.create(
    {
      paymentIntentId: "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7",
      amount: 1000,
      reason: "requestedByPayer",
      idempotencyKey: crypto.randomUUID(),
    },
    { instanceId: crypto.randomUUID() },
  );
  ```

  ```bash CLI theme={null}
  natural refunds create \
    --payment-intent-id pmi_019d0a1b2c3d4e5f60718293a4b5c6d7 \
    --amount 1000 \
    --reason requestedByPayer \
    --x-instance-id "$(uuidgen)" \
    --idempotency-key "$(uuidgen)"
  ```

  ```text MCP theme={null}
  Refund $10 of payment intent pmi_019d0a1b2c3d4e5f60718293a4b5c6d7 at the payer's request.
  ```

  ```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",
          "amount": 1000,
          "reason": "requestedByPayer"
        }
      }
    }'
  ```
</CodeGroup>

The response includes the refund ID and its status.

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

## Watch the refund

[Get the refund](/api-reference/refunds/get-refund) to check its status, or subscribe to `refund.succeeded` and `refund.failed` [webhooks](/api-reference/event-catalog).

<CodeGroup>
  ```python Python theme={null}
  result = client.refunds.get(refund.data.id)
  ```

  ```typescript TypeScript theme={null}
  const result = await client.refunds.get({ refundId: refund.data.id });
  ```

  ```bash CLI theme={null}
  natural refunds get --refund-id rfd_019d0a1b2c3d4e5f60718293a4b5c6e0
  ```

  ```text MCP theme={null}
  Has that refund completed?
  ```

  ```bash cURL theme={null}
  curl https://api.natural.com/refunds/rfd_019d0a1b2c3d4e5f60718293a4b5c6e0 \
    -H "Authorization: Bearer $NATURAL_API_KEY"
  ```
</CodeGroup>

A finished refund has status `succeeded` or `failed`. If it fails, check `failure` for the reason.

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

## List refunds

[List refunds](/api-reference/refunds/list-refunds) to review recent activity. Filter by `paymentIntentId` or `cardPaymentId` to see refunds for one payment.

<CodeGroup>
  ```python Python theme={null}
  refunds = client.refunds.list(
      payment_intent_id="pmi_019d0a1b2c3d4e5f60718293a4b5c6d7",
  )
  ```

  ```typescript TypeScript theme={null}
  const refunds = await client.refunds.list({
    paymentIntentId: "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7",
  });
  ```

  ```bash CLI theme={null}
  natural refunds list \
    --payment-intent-id pmi_019d0a1b2c3d4e5f60718293a4b5c6d7
  ```

  ```text MCP theme={null}
  List refunds for payment intent pmi_019d0a1b2c3d4e5f60718293a4b5c6d7.
  ```

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

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

## Handle a refused refund

* **Another refund is pending:** wait for it to finish before requesting another.
* **The amount is too high:** request no more than the remaining refundable amount.
* **Insufficient funds:** add funds to your wallet, then retry.
* **A chargeback blocks the refund:** review the dispute before proceeding.

See [Refund errors](/api-reference/errors/refunds) for the full list of codes and causes.


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