---
title: "Create payment request"
method: POST
path: "/payment-requests"
tags: ["PaymentRequests"]
---

# Create payment request

`POST /payment-requests`

Create a payment request

## Headers

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

## Request body

- object
  - `data` object, required
    - `attributes` object, required
      - `customerPartyId` string — Requester party ID (pty_*). Omit to request into your own wallet; provide for delegated payment requests on behalf of a customer.
      - `walletId` string — Wallet (wal_*) that should receive the funds. Omit to use the requester party's default wallet.
      - `amount` integer, required — Amount in cents.
      - `currency` 'USD' — Currency code (currently only USD).
      - `description` string — Free-form description shown to the payer. Maximum 80 characters.
      - `payerName` string — Display name of the payer. Maximum 32 characters.
      - `payer` union, required — Who pays: exactly one typed email, phone, party ID, agent ID, or handle value.
        - 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).
      - `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` 'paymentRequest', required
    - `id` string, required — Payment request ID (prq_*).
    - `attributes` object, required
      - `amount` integer, required — Amount in cents.
      - `currency` string, required — Currency code.
      - `status` 'OPEN' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'RETURNED' | 'CANCELED' | 'DECLINED' | 'EXPIRED', required — Payment request status.
      - `payerCanPay` boolean, required — Whether the request's stored lifecycle currently allows the addressed payer to attempt fulfillment (stored OPEN, no prior payment attempt, not expired). Server-computed eligibility only — does not guarantee caller authorization or payment-source readiness, and does not consider paymentLinkExpiresAt (the hosted payment page enforces its own expiry).
      - `payerCanDecline` boolean, required — Whether the request's stored lifecycle currently allows the addressed payer to decline it (stored OPEN). Server-computed eligibility only — does not guarantee caller authorization, and does not consider request expiry or paymentLinkExpiresAt (the hosted payment page enforces its own expiry).
      - `description` string, nullable, required — Free-form description provided at creation. Maximum 80 characters.
      - `requesterName` string, nullable, required — Display name of the party requesting payment.
      - `requesterEmail` string, nullable, required — Email of the party requesting payment.
      - `requesterAvatarUrl` string, uri, nullable, required — Public avatar URL for the party requesting payment, if one is set.
      - `requesterHandle` string, nullable, required — The requesting party's composed public handle (@namespace), or null when it has none.
      - `walletName` string, nullable, required — Receiving wallet name, or null when unnamed or hidden from the caller.
      - `payerName` string, nullable, required — Display name of the payer.
      - `payerEmail` string, nullable, required — Email of the payer, or null when none is known.
      - `payerAvatarUrl` string, uri, nullable, required — Public avatar URL for the payer party, if one is set.
      - `payerHandle` string, nullable, required — The resolved payer party's composed public handle (@namespace), or null when off-platform or handle-less.
      - `payerPhone` string, nullable, required — Payer phone number when addressed by phone.
      - `payerPartyId` string, nullable, required — Natural party ID (pty_*) resolved for the payer, including agent owner parties.
      - `payerIdentifierType` 'email' | 'phone' | 'party_id' | 'agent_id' | 'handle', required — Identifier type used to address the payer.
      - `payerIdentifier` string, required — Identifier value used to address the payer.
      - `initiatorParty` object, nullable, required — The party that created this payment request, or null when unresolved. When an agent created it, this is the agent's owning party.
        - `id` string, required
        - `name` string, required
        - `handle` string, nullable, required — The initiating party's composed public handle (@namespace), or null when it has none.
      - `initiatorAgent` object, nullable, required — Agent that created this payment request, when one did. Otherwise null.
        - `id` string, required
        - `name` string, required
        - `handle` string, nullable, required — The agent's composed public handle (@namespace-slug), or null when it has none.
      - `paymentLinkUrl` string, uri, required — URL the payer visits to complete payment.
      - `transactionId` string, nullable, required — ID of the transaction created by the most recent payment attempt, or null if no attempt yet.
      - `createdAt` string, required — When the payment request was created.
      - `updatedAt` string, required — When the payment request was last updated.
    - `relationships` object, required
      - `requesterParty` object, required — Party requesting the payment.
        - `data` object, required — Related resource identifier.
          - `type` 'party', required
          - `id` string, required
      - `payerParty` object, required — Resolved payer party, if the payer is known to Natural.
        - `data` object, nullable, required — Related resource identifier.
          - `type` 'party', 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)