---
title: "Get payment request"
method: GET
path: "/payment-requests/{paymentRequestId}"
tags: ["PaymentRequests"]
---

# Get payment request

`GET /payment-requests/{paymentRequestId}`

Get a payment request

## Path parameters

- `paymentRequestId` string, required — Payment request ID (prq_*).

## Query parameters

- `partyId` string — Effective party ID (pty_*) for delegated payment request access.

## Headers

- `X-Agent-ID` string, nullable
- `X-Instance-ID` string, nullable

## Response `200`

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
      - `wallet` object, required — Wallet that receives the funds.
        - `data` object, required — Related resource identifier.
          - `type` 'wallet', 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
      - `payerAgent` object, required — Payer agent, or null unless addressed by agent ID or agent handle.
        - `data` object, nullable, required — Related resource identifier.
          - `type` 'agent', required
          - `id` string, required
      - `payment` object, required — Payment submitted for this payment request, if one exists.
        - `data` object, nullable, required — Related resource identifier.
          - `type` 'payment', 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)