---
title: "Cancel payment"
method: POST
path: "/payments/{paymentId}/cancel"
tags: ["Payments"]
---

# Cancel payment

`POST /payments/{paymentId}/cancel`

Cancel a payment before the recipient begins claiming it

## Path parameters

- `paymentId` string, required — Payment ID (pay_*).

## Headers

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

## Request body

- object
  - `data` object
    - `attributes` object, required
      - `customerPartyId` string — Defaults to your party. To act for another party, pass the ID of a party that has authorized you to act on its behalf.

## Response `200`

Successful Response

- object
  - `data` object, required
    - `type` 'payment', required — Resource type. Always `payment`.
    - `id` string, required — Payment ID (pay_*).
    - `attributes` object, required
      - `amount` integer, required — Amount in cents.
      - `currency` string, required — Currency code.
      - `status` 'CREATED' | 'PROCESSING' | 'PENDING_CLAIM' | 'IN_REVIEW' | 'COMPLETED' | 'FAILED' | 'RETURNED' | 'APPROVAL_DENIED' | 'CANCELED', required — Payment status.
      - `description` string, nullable, required — Payment description.
      - `tags` object, required — Metadata visible to anyone who can read the resource.
      - `fee` object, nullable, required — Fee added to your cost as the sender. Null when no fee applies, the fee was voided, or your party is not the fee payer.
        - `amount` integer, required — Fee amount in cents.
        - `currency` 'USD', required — Currency of the fee.
        - `payer` 'sender', required — Party role charged the fee.
        - `applied` 'on_top', required — The fee is added to the sender's cost without reducing the principal amount.
      - `submittedAt` string, nullable, required — RFC 3339 timestamp when this payment was submitted to money movement, or null while unsubmitted.
      - `terminalAt` string, nullable, required — RFC 3339 timestamp when this payment reached a terminal status, or null while in flight.
      - `failure` object, nullable, required — Failure details when this payment failed.
        - `code` string, nullable, required — Reason code, when available.
        - `reason` string, nullable, required — Reason text, when available.
      - `return` object, nullable, required — Return details when this payment was returned.
        - `code` string, nullable, required — Reason code, when available.
        - `reason` string, nullable, required — Reason text, when available.
      - `claim` object, nullable, required — Claim lifecycle for payments sent to an off-platform recipient, or null when this payment is not claim-based.
        - `startedAt` string, nullable, required — RFC 3339 timestamp when the recipient began claiming this payment, or null while unclaimed or unobserved.
        - `claimedAt` string, nullable, required — RFC 3339 timestamp when the recipient claimed this payment, or null while unclaimed.
        - `unboundAt` string, nullable, required — RFC 3339 timestamp when a claimed payment detached from its recipient, or null.
      - `createdAt` string, required — RFC 3339 timestamp when this payment was created.
      - `updatedAt` string, nullable, required — RFC 3339 timestamp when this payment was last updated, or null.
    - `relationships` object, required
      - `sender` object, required — Party that initiated the payment, when the sender is on Natural.
        - `data` object, nullable, required — Related resource identifier.
          - `type` 'party', required — Resource type. Always `party`.
          - `id` string, required
      - `senderAgent` object, required — Sending agent, or null when the payment was not sent by an agent.
        - `data` object, nullable, required — Related resource identifier.
          - `type` 'agent', required — Resource type. Always `agent`.
          - `id` string, required
      - `recipient` object, required — Recipient party for this payment, when known.
        - `data` object, nullable, required — Related resource identifier.
          - `type` 'party', required — Resource type. Always `party`.
          - `id` string, required
      - `recipientAgent` object, required — Recipient agent, or null unless addressed by agent ID or agent handle.
        - `data` object, nullable, required — Related resource identifier.
          - `type` 'agent', required — Resource type. Always `agent`.
          - `id` string, required
      - `transaction` object, required — Sender-side transaction for this payment, when available.
        - `data` object, nullable, required — Related resource identifier.
          - `type` 'transaction', required — Resource type. Always `transaction`.
          - `id` string, required
      - `paymentRequest` object, required — Payment request that produced this payment, when applicable.
        - `data` object, nullable, required — Related resource identifier.
          - `type` 'paymentRequest', required — Resource type. Always `paymentRequest`.
          - `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-23** `6f76de3472aa` — 5 info
  - added the required property `data/attributes/claim` to the response with the `200` status
  - added the required property `data/attributes/failure` to the response with the `200` status
  - added the required property `data/attributes/return` to the response with the `200` status
  - added the required property `data/attributes/submittedAt` to the response with the `200` status
  - …1 more
- **2026-09-23** `bcf3b028c3e5` — 2 info
  - added optional request body
  - added the required property `data/attributes/fee` to the response with the `200` status
- **2026-09-02** `c7c12da5915f` — 12 info
  - added the optional property `errors/items/meta/limitScope` to the response with the `400` status
  - added the optional property `errors/items/meta/limitScope` to the response with the `401` status
  - added the optional property `errors/items/meta/limitScope` to the response with the `403` status
  - added the optional property `errors/items/meta/limitScope` to the response with the `404` status
  - …8 more
- **2026-08-27** `359d267dca88` — 1 info
  - deleted the `header` request parameter `X-Agent-ID` with deprecation
- **2026-08-23** `b1ad79e918ac` — 1 info
  - `header` request parameter `X-Agent-ID` was deprecated

[Full history](https://skmtc.dev/natural/apis/natural-api/changes/payments/:paymentId/cancel/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/acc8f2f3d25e?raw)