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

# Create payment request

`POST /payment-requests`

Create a payment request. Natural notifies the payer directly: email and phone payers receive the pay link, on-platform parties receive a dashboard deep-link, and agent and handle payers receive only the in-app webhook.

## Headers

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

## Request body

- object
  - `data` object, required — Resource object
    - `attributes` object, required — Payment request creation attributes
      - `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 that should receive the funds. Omit to use the requester party's default wallet.
      - `amount` integer, required — Amount in minor units (cents for USD)
      - `currency` 'USD' — Currency code (currently only USD)
      - `description` string — Free-form description shown to the payer. Maximum 500 characters.
      - `payerName` string — Display name of the payer
      - `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 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)

## Response `201`

Successful Response

- object
  - `data` object, required
    - `type` 'paymentRequest', required — Resource type
    - `id` string, required — Resource ID (prq_*)
    - `attributes` object, required — Resource attributes
      - `amount` integer, required — Amount in cents
      - `currency` string, required — Currency code
      - `status` 'OPEN' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'RETURNED' | 'CANCELED' | 'DECLINED' | 'EXPIRED', required — Current status of the payment request
      - `description` string, nullable, required — Free-form description provided at creation. Maximum 500 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
      - `payerName` string, nullable, required — Display name of the payer
      - `payerEmail` string, nullable, required — Email of the payer if addressed by email
      - `payerAvatarUrl` string, uri, nullable, required — Public avatar URL for the payer party, if one is set
      - `payerPhone` string, nullable, required — Phone of the payer in E.164 format if 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 — Which identifier type was used to address the payer
      - `payerIdentifier` string, required — The identifier value used to address the payer
      - `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 — ISO 8601 timestamp when the payment request was created
      - `updatedAt` string, required — ISO 8601 timestamp when the payment request was last updated
    - `relationships` object, required — Resource relationships
      - `requesterParty` object, required — Party requesting the payment
        - `data` object, required — Related resource identifier
          - `type` 'party', required — Resource type
          - `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 — 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

## Changes

- **2026-07-14** `8cc2aed45847` — 2 info
  - added the required property `data/attributes/payerAvatarUrl` to the response with the `201` status
  - added the required property `data/attributes/requesterAvatarUrl` to the response with the `201` status

[Change history](https://skmtc.dev/natural/apis/natural-api/changes/payment-requests/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-service-production.skmtc.workers.dev/v1/apis/natural/natural-api/revisions/8cc2aed45847/schema)