SOsolana
Payments

Create payment request

Changed on

Creates a payment request: an amount of one token for a payer to send to a custody wallet in the caller's project, through the request's hosted payment link. 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.

post/v1/payments/requests

Request

  • Base URL
    http://localhost:8787
  • Auth
    HTTP bearer

Headers

x-project-idstring

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

Example:prj_example
Idempotency-Keystring

Optional, and honored when sent. 1-255 printable ASCII characters; send a UUID per logical operation and reuse it on every retry. Within 24 hours, a retry with the same key and the same request returns the stored status and body with the response header Idempotent-Replayed: true. Keys are scoped to the credential: within 24 hours, the same key with a different request, or from a different credential, returns 422 IDEMPOTENCY_KEY_REUSED; after that, the same key from a different credential runs as a new request. A rotated API key is a new credential, so after any rotation read the resource with GET to see whether the original request ran, and never resend a money request under the new credential without checking first. A key whose original request is still running returns 409 IDEMPOTENCY_KEY_IN_FLIGHT with Retry-After. A 400, 401, 403, 409 or 429 refusal is not stored, so the same key runs again once the cause is fixed. Access is checked before the key on every request, so a refused request never claims the key, and a credential that has since lost access to the named resource gets 403 instead of the stored response. A replay is a snapshot of the original response: read the current state with GET instead of sending the request again. If the original request never recorded its outcome (it crashed), a same-key retry gets 409 IDEMPOTENCY_KEY_IN_FLIGHT until 15 minutes plus the route's lease have passed since the original was sent (about 16 minutes, or about 20 for transfer batches), then 409 IDEMPOTENCY_KEY_OUTCOME_UNKNOWN with no Retry-After, as does every later retry with that key: read the resource with GET to see whether it ran, then send again with a new key. A 5xx is stored and replayed like any other answer; retry it with a new key.

Example:idempotency_example_12345

Request body

walletIdstring required

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.

tokenstring required

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

amountstring required

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

expiresAtstring date-time nullable

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

Example request

{
  "walletId": "privy_wallet_123",
  "token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "amount": "10.00",
  "expiresAt": null
}

Response

Payment request created

Example response

{
  "data": {
    "id": "preq_example",
    "destinationAddress": "So11111111111111111111111111111111111111112",
    "amount": "100.00",
    "reference": "So11111111111111111111111111111111111111112",
    "status": "canceled",
    "expiresAt": "2025-01-01T00:00:00.000Z",
    "lastCheckedAt": "2025-01-01T00:00:00.000Z",
    "canceledAt": "2025-01-01T00:00:00.000Z",
    "lifecycle": [
      {
        "status": "canceled",
        "at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-01T00:00:00.000Z",
    "publicToken": "example-public-token"
  },
  "meta": {
    "requestId": "req_example",
    "timestamp": "2025-01-01T00:00:00.000Z"
  }
}

Changes