---
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 use the party default for user or party API calls, or the agent default for the current customer connection when acting through a connected agent. Owned agents use their own agent default.

## 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.
      - `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.
      - `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-23** `6f76de3472aa` — 5 info
  - added the required property `data/attributes/claim` to the response with the `201` status
  - added the required property `data/attributes/failure` to the response with the `201` status
  - added the required property `data/attributes/return` to the response with the `201` status
  - added the required property `data/attributes/submittedAt` to the response with the `201` status
  - …1 more
- **2026-09-23** `bcf3b028c3e5` — 1 info
  - added the required property `data/attributes/fee` to the response with the `201` 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 warning, 1 info
  - removed the request property `data/attributes/disableNotifications`
  - `header` request parameter `X-Agent-ID` was deprecated

[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/ca3882d75a00?raw)