---
title: "List payment requests"
method: GET
path: "/payment-requests"
tags: ["PaymentRequests"]
---

# List payment requests

`GET /payment-requests`

List payment requests created by the authenticated requester party. Set includeCompleted to false to exclude completed payment requests.

## Query parameters

- `limit` integer — Results per page (1-100)
- `cursor` string — Pagination cursor returned by the previous response
- `partyId` string — Effective party ID (pty_*) for delegated payment request access.
- `includeCompleted` union — Whether to include completed payment requests. Defaults to true.
  - boolean
  - string

## Headers

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

## Response `200`

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
      - `wallet` object, required — Wallet that receives the funds
        - `data` object, required — Related resource identifier
          - `type` 'wallet', 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
      - `payment` object, required — Payment submitted for this payment request, if one exists.
        - `data` object, nullable, required — Related resource identifier
          - `type` 'payment', required — Resource type
          - `id` string, required
  - `meta` object, required
    - `pagination` object, required
      - `hasMore` boolean, required
      - `nextCursor` string, nullable, 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/items/attributes/payerAvatarUrl` to the response with the `200` status
  - added the required property `data/items/attributes/requesterAvatarUrl` to the response with the `200` status

[Change history](https://skmtc.dev/natural/apis/natural-api/changes/payment-requests/get.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)