---
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 — Recipient identifier. Provide exactly one typed email, phone, party ID, agent ID, or handle (@handle[-slug]) value. Agent recipients (agent ID or @handle-slug) credit the agent's preferred wallet when one is set, otherwise the owner party's default wallet.
        - object
          - `type` 'email', required
          - `value` string, email, required — Email address
        - object
          - `type` 'phone', required
          - `value` string, required — Phone number in E.164 format
        - 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 500 characters.
      - `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
    - `id` string, required
    - `attributes` object, required — Resource attributes
      - `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
    - `relationships` object, required — Resource relationships
      - `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
          - `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
          - `id` string, required
      - `recipientAgent` object, required — Recipient agent when the caller addressed an agent ID. Null otherwise, including when the recipient was addressed as an email, phone, or party ID.
        - `data` object, nullable, required — Related resource identifier
          - `type` 'agent', required — Resource type
          - `id` string, required
      - `transaction` object, required — Sender-side transaction row for this payment, when available.
        - `data` object, nullable, required — Related resource identifier
          - `type` 'transaction', required — Resource type
          - `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
          - `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.dev/natural/apis/natural-api.md) · [All operations](https://skmtc.dev/natural/apis/natural-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/natural/natural-api/revisions/8cc2aed45847/schema)