---
title: "Create refund"
method: POST
path: "/refunds"
tags: ["Refunds"]
---

# Create refund

`POST /refunds`

## Request

- Base URL: `https://api.natural.com`
- URL: `https://api.natural.com/refunds`
- Auth: HTTP bearer

Refund a card payment

## Headers

- `Idempotency-Key` string, required
- `X-Instance-ID` string, nullable

## Request body

- object
  - `data` object, required
    - `attributes` object, required
      - `customerPartyId` string: Customer party to act for (pty_*). Omit for your own account. Requires authorization from that customer.
      - `paymentIntentId` string: Payment intent to refund (pmi_*). Supply either paymentIntentId or cardPaymentId, not both.
      - `cardPaymentId` string: Successful card payment to refund (cpy_*). Supply either cardPaymentId or paymentIntentId, not both.
      - `amount` integer: Amount in US cents. Omit to refund the full remaining amount.
      - `reason` 'duplicate' | 'fraudulent' | 'requestedByPayer': Why the refund was requested.

## Response `201`

Successful Response

- object
  - `data` Refund, required
    - `id` string, required: Refund ID (rfd_*).
    - `type` 'refund', required: Resource type. Always `refund`.
    - `attributes` object, required
      - `amount` integer, required: Amount in US cents.
      - `currency` 'USD', required: Currency code.
      - `reason` 'duplicate' | 'fraudulent' | 'requestedByPayer', nullable, required: Why the refund was requested.
      - `status` 'pending' | 'succeeded' | 'failed', required: Refund status. Succeeded means the refund was processed, but the cardholder’s bank may not have posted the credit yet.
      - `failure` object, nullable, required: Failure details. Null unless the refund failed.
        - `code` string, nullable, required: Failure code, when known. New codes may be added.
        - `reason` string, nullable, required: Explanation of the failure.
      - `receiptUrl` string, nullable, required: The refunded payment's hosted receipt page, which lists this refund.
      - `createdAt` string, required: RFC 3339 timestamp when the refund was created.
      - `updatedAt` string, required: RFC 3339 timestamp when the refund was last updated.
    - `relationships` object, required
      - `paymentIntent` object, required: The intent whose payment is refunded.
        - `data` object, required: Related resource identifier.
          - `type` 'paymentIntent', required: Resource type. Always `paymentIntent`.
          - `id` string, required
      - `cardPayment` object, required: The card payment refunded.
        - `data` object, required: Related resource identifier.
          - `type` 'cardPayment', required: Resource type. Always `cardPayment`.
          - `id` string, required
      - `customerParty` object, required: The party that received the original payment.
        - `data` object, required: Related resource identifier.
          - `type` 'party', required: Resource type. Always `party`.
          - `id` string, required

## Other responses

- `400`: Validation Error
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing.
- `409`: Conflict
- `422`: Validation Error. The response contains one error object for each invalid request value.
- `428`: Precondition Required
- `429`: Too Many Requests
- `500`: Internal Server Error
- `501`: Not Implemented
- `502`: Bad Gateway
- `503`: Service Unavailable

## Changes

- **2026-09-29** `4fab756be152`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/natural/apis/natural-api/changes/refunds/post.md)

---

[API](https://skmtc.dev/natural/apis/natural-api.md) - [All operations](https://skmtc.dev/natural/apis/natural-api/llms.txt) - [OpenAPI document](https://skmtc.dev/natural/apis/natural-api/revisions/59c1208fa5dc?raw)