Create payment request

POST/v1/payments/requestsRun in dashboard

Requires payment_requests.manage. walletId is the provider wallet ID (walletId from GET /v1/wallets), not the SDP Wallet ID transfers take; an unknown wallet, or one outside the project, returns 404. amount is a decimal string with at most the mint's decimals, so 0.05 and 0.050 are the same request; more decimals return 400. A native SOL request is refused with 409 AMOUNT_BELOW_RENT_MINIMUM when the wallet has no account and the amount is below the rent-exempt minimum. The response is the only one besides GET /v1/payments/requests/{paymentRequestId}/link that carries publicToken. Accepts an Idempotency-Key: a retry with the same key and request returns the original payment request instead of creating a second one.

Requires an API key with the payment_requests.manage action.

HeadersCopy Anchor Link

• x-project-id · string · min length 1 · example prj_example

  Required for dashboard sessions. API keys use their assigned project.

• Idempotency-Key · string

  Use a unique 1–255 printable ASCII key per operation. Reuse it with the same request on retries. An in-flight attempt returns 409; a changed request returns 422. Retry and recovery rules.

Request bodyCopy Anchor Link

application/json · required

Create payment request payload.

• walletId · string · required · min length 1 · example privy_wallet_123

  Receiving custody wallet in the caller's project. Provider wallet ID: the walletId field returned by GET /v1/wallets. The wallet record id and the public key are not accepted. An SDP Wallet ID (cwlt_...) returns 404.

• token · string · required · example EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

  Mint address of the token to request. Symbols are not accepted; for native SOL, pass So11111111111111111111111111111111111111112.

• amount · string · required · example 10.00

  Amount to request in UI units, as a decimal string greater than zero with no more decimal places than the mint has.

• expiresAt · string | null · format date-time · default null · example 2026-12-01T00:00:00.000Z

  When the request stops accepting payment, as an ISO 8601 timestamp. Null or omitted: it never expires.

ResponsesCopy Anchor Link

• 201 Payment request created

  • data · object · required

    A new payment request, with its link token.

    • id · string · required · example preq_example

      SDP payment request ID.

    • organizationId · string · required

      Organization ID.

    • projectId · string | null · required

      Project ID.

    • walletId · string · required

      Receiving custody wallet's provider ID.

    • destinationAddress · string · required · min length 32 · max length 44 · example So11111111111111111111111111111111111111112

      Address the payment is sent to.

    • token · string · required

      Token mint address.

    • amount · string · required · example 100.00

      Token amount in UI units (decimal string).

    • reference · string · required · min length 32 · max length 44 · example So11111111111111111111111111111111111111112

      Solana Pay reference account that identifies the payment on chain.

    • status · string · required · one of awaiting_payment, paid, canceled, expired · example canceled

      Payment request status. awaiting_payment is open; paid was settled by an on-chain payment; canceled and expired closed without one.

    • expiresAt · string | null · required · format date-time · example 2025-01-01T00:00:00.000Z

      Expiry, if any.

    • fulfilledByTransferId · string | null · 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 | null · required · format date-time · example 2025-01-01T00:00:00.000Z

      When SDP last read the chain for the payment.

    • canceledByApiKeyId · string | null · required

      The API key that canceled the request; null when a member did, or it is not canceled.

    • canceledByUserId · string | null · required

      User ID of the member who canceled the request; null when an API key did, or it is not canceled.

    • canceledAt · string | null · required · format date-time · example 2025-01-01T00:00:00.000Z

      When it was canceled.

    • lifecycle · object[] · required

      Every status the request entered, oldest first.

      • status · string · required · one of awaiting_payment, paid, canceled, expired · example canceled

        Payment request status. awaiting_payment is open; paid was settled by an on-chain payment; canceled and expired closed without one.

      • at · string · required · format date-time · example 2025-01-01T00:00:00.000Z

        ISO 8601 timestamp.

    • createdBy · string | null · required

      User ID of the member, or of the API key's creator, who created it.

    • createdAt · string · required · format date-time · example 2025-01-01T00:00:00.000Z

      ISO 8601 timestamp.

    • updatedAt · string · required · format date-time · example 2025-01-01T00:00:00.000Z

      ISO 8601 timestamp.

    • publicToken · string · required · example example-public-token

      Token behind the request's hosted payment link, /pay/{publicToken}. Anyone holding it can build the request's fee-sponsored payment transaction, so share it only with the payer. Reads never return it; get it again with GET /v1/payments/requests/{paymentRequestId}/link.

  • meta · object · required

    Response metadata.

    • requestId · string · required · min length 1 · example req_example

      Request identifier for tracing.

    • timestamp · string · required · format date-time · example 2025-01-01T00:00:00.000Z

      ISO 8601 timestamp.

• 400 Bad Request

  • error · object · required

    Standard error payload.

    • code · string · required

      Machine-readable error code.

    • message · string · required

      Human-readable error message.

    • details · object

      Optional error details for debugging.

      • * · any

  • meta · object

    • requestId · string · min length 1 · example req_example

      Request identifier for tracing.

• 401 Unauthorized

  Same fields as 400.

• 403 Forbidden. Requires the payment_requests.manage 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.

  Same fields as 400.

• 404 Not Found

  Same fields as 400.

• 409 Conflict

  Same fields as 400.

• 422 Unprocessable Entity

  Same fields as 400.

• 500 Internal Server Error

  Same fields as 400.

• 503 Service Unavailable

  Same fields as 400.