---
title: "List payment requests"
method: GET
path: "/v1/payments/requests"
tags: ["Payments"]
---

# List payment requests

`GET /v1/payments/requests`

## Request

- Base URL: `http://localhost:8787`
- URL: `http://localhost:8787/v1/payments/requests`
- Auth: HTTP bearer

Lists the caller's project's payment requests, newest first. Requires `payment_requests.read`. An open request past its `expiresAt` reads as `expired`. Records never carry `publicToken`.

## Query parameters

- `page` integer: Page number, starting at 1.
- `pageSize` integer: Results per page, 1 to 100.
- `status` 'awaiting_payment' | 'paid' | 'canceled' | 'expired': Payment request status. `awaiting_payment` is open; `paid` was settled by an on-chain payment; `canceled` and `expired` closed without one.

## Headers

- `x-project-id` string: Required for dashboard sessions. API keys use their assigned project.

## Response `200`

Payment request list

- object: Standard success response envelope.
  - `data` object, required: Payment request list response payload.
    - `paymentRequests` object[], required
      - `id` string, required: SDP payment request ID.
      - `organizationId` string, required: Organization ID.
      - `projectId` string, nullable, required: Project ID.
      - `walletId` string, required: Receiving custody wallet's provider ID.
      - `destinationAddress` string, required: Address the payment is sent to.
      - `token` string, required: Token mint address.
      - `amount` string, required: Token amount in UI units (decimal string).
      - `reference` string, required: Solana Pay reference account that identifies the payment on chain.
      - `status` 'awaiting_payment' | 'paid' | 'canceled' | 'expired', required: Payment request status. `awaiting_payment` is open; `paid` was settled by an on-chain payment; `canceled` and `expired` closed without one.
      - `expiresAt` string, date-time, nullable, required: Expiry, if any.
      - `fulfilledByTransferId` string, nullable, required: The inbound transfer that paid the request.
      - `paidLate` boolean, required: Whether the payment landed after the request expired or was canceled. A payer who signed before then can still pay.
      - `lastCheckedAt` string, date-time, nullable, required: When SDP last read the chain for the payment.
      - `canceledByApiKeyId` string, nullable, required: The API key that canceled the request; null when a member did, or it is not canceled.
      - `canceledByUserId` string, nullable, required: User ID of the member who canceled the request; null when an API key did, or it is not canceled.
      - `canceledAt` string, date-time, nullable, required: When it was canceled.
      - `lifecycle` object[], required: Every status the request entered, oldest first.
        - `status` 'awaiting_payment' | 'paid' | 'canceled' | 'expired', required: Payment request status. `awaiting_payment` is open; `paid` was settled by an on-chain payment; `canceled` and `expired` closed without one.
        - `at` string, date-time, required: ISO 8601 timestamp.
      - `createdBy` string, nullable, required: User ID of the member, or of the API key's creator, who created it.
      - `createdAt` string, date-time, required: ISO 8601 timestamp.
      - `updatedAt` string, date-time, required: ISO 8601 timestamp.
    - `total` integer, required
    - `page` integer, required
    - `pageSize` integer, required
  - `meta` object, required: Response metadata.
    - `requestId` string, required: Request identifier for tracing.
    - `timestamp` string, date-time, required: ISO 8601 timestamp.

## Other responses

- `400`: Error
- `401`: Error
- `403`: Forbidden. Requires the `payment_requests.read` action: an API key must hold it (a module's `manage` or `execute` also covers its `read`), and a signed-in member's organization role must include it. Without it the error is INSUFFICIENT_PERMISSIONS and `error.details.action` names the action. Any other 403 names its own reason.
- `500`: Error

## Changes

- **2026-11-04** `b329212c2291`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/solana/apis/solana-developer-platform-api/changes/v1/payments/requests/get.md)

---

[API](https://skmtc.dev/solana/apis/solana-developer-platform-api.md) - [All operations](https://skmtc.dev/solana/apis/solana-developer-platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/solana/apis/solana-developer-platform-api/revisions/b329212c2291?raw)