---
title: "Create payment"
method: POST
path: "/payments"
tags: ["Payments"]
---

# Create payment

`POST /payments`

Create a payment

## Headers

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

## Request body

- object
  - `data` object, required
    - `attributes` object, required
      - `amount` integer, required — Amount in cents.
      - `counterparty` union, required — Payment recipient. Agent recipients use their preferred wallet or their party's default wallet.
        - object
          - `type` 'email', required
          - `value` string, email, required — Email address.
        - object
          - `type` 'phone', required
          - `value` string, required — Phone number.
        - object
          - `type` 'party_id', required
          - `value` string, required — Natural party ID (pty_*).
        - object
          - `type` 'agent_id', required
          - `value` string, required — Natural agent ID (agt_*).
        - object
          - `type` 'handle', required
          - `value` string, required — Natural handle (@handle or @handle-slug).
      - `customerPartyId` string — Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf.
      - `currency` 'USD' — Currency code.
      - `description` string — Payment description. Maximum 80 characters.
      - `tags` object — Key-value metadata stored on the resource. At most 30 keys; keys 1-128 characters, alphanumeric and underscores; values 1-256 characters. Visible to anyone who can read the resource; do not include sensitive data.
      - `walletId` string — Source wallet ID (wal_*). Omit to pay from the sender party's default wallet.

## Response `201`

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.
      - `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.
      - `claimLink` string, nullable — Link an off-platform recipient uses to claim this payment, or null when the recipient is already on Natural. Returned only here, when the payment is created. The token behind it is never stored, so it cannot be fetched later. It stays valid even if the payment goes through approval. Treat it as a secret: anyone holding the link can claim the funds.
    - `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-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 warning, 1 info
  - removed the request property `data/attributes/disableNotifications`
  - `header` request parameter `X-Agent-ID` was deprecated
- **2026-08-13** `ba1fb54c5939` — 2 info
  - added the new optional request property `data/attributes/tags`
  - added the required property `data/attributes/tags` to the response with the `201` status
- **2026-08-02** `983d5c234522` — 1 warning, 1 info
  - removed the request property `data/attributes/suppressNotifications`
  - added the new optional request property `data/attributes/disableNotifications`

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