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

# Create payment

`POST /payments`

Create a payment

## Headers

- `Idempotency-Key` string, required
- `X-Agent-ID` string, nullable
- `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 — Sender party ID (pty_*). Omit to send from your own wallet; provide for delegated payments on behalf of a customer.
      - `currency` 'USD' — Currency code.
      - `description` string — Payment description. Maximum 80 characters.
      - `walletId` string — Source wallet ID (wal_*). Omit to pay from the sender party's default wallet.
      - `disableNotifications` string[] — Natural notifications to disable for this request. "recipient" silences our message to the counterparty so you can deliver the returned link yourself; the person who initiated the request is always notified. Requires a delegated caller on payments and payment requests, which return 403 otherwise. Omit it, or send an empty array, to have Natural notify as usual.

## Response `201`

Successful Response

- object
  - `data` object, required
    - `type` 'payment', required
    - `id` string, required
    - `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.
      - `createdAt` string, required — When this payment was created.
      - `updatedAt` string, nullable, required — When this payment was last updated.
      - `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
          - `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
          - `id` string, required
      - `recipient` object, required — Recipient party for this payment, when known.
        - `data` object, nullable, required — Related resource identifier.
          - `type` 'party', required
          - `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
          - `id` string, required
      - `transaction` object, required — Sender-side transaction for this payment, when available.
        - `data` object, nullable, required — Related resource identifier.
          - `type` 'transaction', required
          - `id` string, required
      - `paymentRequest` object, required — Payment request that produced this payment, when applicable.
        - `data` object, nullable, required — Related resource identifier.
          - `type` 'paymentRequest', required
          - `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
- `428` — Precondition Required
- `429` — Too Many Requests
- `500` — Internal Server Error
- `501` — Not Implemented
- `502` — Bad Gateway
- `503` — Service Unavailable

---

[API](https://skmtc.net/natural/apis/natural-api.md) · [All operations](https://skmtc.net/natural/apis/natural-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/natural/natural-api/versions/0bb9c54b1f61/schema)