> ## Documentation Index > Fetch the complete documentation index at: https://docs-alpha.pepay.io/llms.txt > Use this file to discover all available pages before exploring further. # List available payment tokens > Returns the token options a payor can use to pay this invoice. Use the returned `network` and `id` (as `tokenId`) to call `POST /api/v1/payments/payment-addresses`. Notes: - In devnet, tokens are returned without settlement quote fields and `availability_status` is `DEVNET`. - In mainnet, tokens include quote fields when available; tokens with `has_settlement_route=false` include `unavailable_reason`. - `availability_status` values: `DEVNET`, `AVAILABLE`, `STALE`, `NO_LIQUIDITY`, `QUOTE_REQUIRED`. - `mode=monitored` (default): only monitored tokens (precomputed snapshot pricing). - `mode=all`: includes non-monitored tokens with `availability_status=QUOTE_REQUIRED`. - `mode=network`: filters to a single network (requires `network` query param). - `available_only=true`: return only tokens with `availability_status=AVAILABLE` (mainnet) or `availability_status=DEVNET` (devnet). - If the invoice is `underpaid`, the response is limited to the locked token/network. ## OpenAPI ````yaml /api-reference/openapi.json get /api/v1/payments/available-tokens openapi: 3.0.0 info: title: Pepay API (SDK-scoped) version: 1.0.0 description: API documentation for Pepay API servers: - url: https://api-beta.pepay.io description: Beta server - url: http://localhost:3000 description: Local development security: - bearerAuth: [] tags: - name: Events description: Events API (history + debugging) for canonical notification envelopes. - name: Metrics description: Internal Prometheus metrics (restricted). - name: WebSockets description: WebSocket streams (upgrade endpoints) and message schemas. - name: Commerce - Devnet Simulator description: > Deterministic devnet-only endpoints for simulating Commerce V2 order state transitions. Use this when integrating as a merchant on devnet to test your backend/UI against realistic order lifecycle changes (payment confirmation, settlement gating, placement, tracking, cancellation, refunds) without placing real retailer orders or sending real on-chain refunds. How it works: - Requires a devnet `X-Commerce-Api-Key` (merchant-scoped). - Only operates on orders created in `networkEnvironment=devnet`. - Updates the order using the same reducer/persistence paths used in mainnet (provider snapshots are simulated). - After each simulation, Pepay emits the normal `commerce.order.updated` merchant webhook event. - name: Merchant Checkout description: > Merchant-scoped **three-step** checkout flow: 1) `POST /api/commerce/merchant/checkout/estimate` — validate items against current eligible offers and return `validItems[]` + `invalidItems[]`. 2) `POST /api/commerce/merchant/checkout/address` — attach and validate a shipping address for the estimate. 3) `POST /api/commerce/merchant/checkout/invoice` — create the final invoice + commerce order. Cart behavior (when `useCart: true`): - The estimate call **reads** the saved cart but does **not** remove or modify cart items. - Items with no eligible offers are returned in `invalidItems[]`. - To remove items from the saved cart, call the Merchant Cart APIs (`PUT /api/commerce/merchant/carts/items/:itemId` with `quantity: 0`, or `DELETE /api/commerce/merchant/carts/items/:itemId`). - To exclude items for *this checkout attempt* without mutating the cart, use `itemOverrides[]` with `quantity: 0`. - name: Payment Sessions description: > Payor-facing APIs used by the hosted payment page and other embedded checkout clients. Canonical base path: - All documented endpoints are under `/api/v1/payments/*`. Authentication: - These endpoints do **not** accept merchant API keys or bearer JWTs. - Send `x-session-token` and `x-signature` headers on every request (both are returned when creating an invoice). Typical flow: 1) Create an invoice (`POST /api/v1/invoices`) → receive `payment_url`, `session_token`, `signature`. 2) Render/open the `payment_url` for the payor. 3) Fetch invoice context (`GET /api/v1/payments/session-details`). 4) List supported tokens (`GET /api/v1/payments/available-tokens`). 5) Allocate a payment address (`POST /api/v1/payments/payment-addresses`) → use `ws_connection` for `/ws/payment`. 6) Track progress via polling (`GET /api/v1/payments/payment-status`) and/or websocket (`/ws/payment`). Security notes: - Treat `session_token` and `signature` as sensitive values (anyone with them can read the invoice/payment status). - Do not store them in long-lived browser storage; prefer in-memory usage on the payment page. - name: Quotes description: Token settlement quotes and rate calculations - name: Webhooks description: > Webhook endpoint management and delivery history for canonical notifications. Delivery model: - At-least-once delivery; receivers must dedupe by `event.id` (also sent as `X-Pepay-Event-ID`). - Payloads are canonical `PepayEvent` objects and match websocket `event_v1` frames for the same event type. Security: - Endpoints must be HTTPS. - Deliveries are signed using `HMAC_SHA256("${timestamp_ms}.${raw_body}")` and sent in `X-Pepay-Signature`. paths: /api/v1/payments/available-tokens: get: tags: - Payment Sessions summary: List available payment tokens description: > Returns the token options a payor can use to pay this invoice. Use the returned `network` and `id` (as `tokenId`) to call `POST /api/v1/payments/payment-addresses`. Notes: - In devnet, tokens are returned without settlement quote fields and `availability_status` is `DEVNET`. - In mainnet, tokens include quote fields when available; tokens with `has_settlement_route=false` include `unavailable_reason`. - `availability_status` values: `DEVNET`, `AVAILABLE`, `STALE`, `NO_LIQUIDITY`, `QUOTE_REQUIRED`. - `mode=monitored` (default): only monitored tokens (precomputed snapshot pricing). - `mode=all`: includes non-monitored tokens with `availability_status=QUOTE_REQUIRED`. - `mode=network`: filters to a single network (requires `network` query param). - `available_only=true`: return only tokens with `availability_status=AVAILABLE` (mainnet) or `availability_status=DEVNET` (devnet). - If the invoice is `underpaid`, the response is limited to the locked token/network. parameters: - in: query name: mode schema: type: string enum: - monitored - all - network default: monitored description: Controls whether non-monitored tokens are included. - in: query name: network schema: type: string enum: - ethereum - base - solana - avalanche - ton - bsc - arbitrum - optimism - cardano - sui required: false description: >- Required when `mode=network`. Filters tokens to the given network (lowercase). - in: query name: available_only schema: type: boolean default: false required: false description: >- When true, only returns tokens that are currently available for the invoice amount. responses: '200': description: Token list content: application/json: schema: $ref: >- #/components/schemas/Getapiv1paymentsavailable-tokensResponse200 examples: mainnet: value: - id: 1 token_symbol: USDC token_name: USDC token_type: erc20 network: ethereum token_decimals: 6 token_address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' requires_memo: false photo_uri: >- https://assets.coingecko.com/coins/images/6319/small/USD_Coin_icon.png is_monitored: true has_settlement_route: true settlement_rate: 1.02 settlement_cost_usd: 102 is_same_token_settlement: false tier: '100' tier_fee: 0 availability_status: AVAILABLE rate_updated_at: 1704110400 - id: 2 token_symbol: ETH token_name: ETH token_type: native network: ethereum token_decimals: 18 token_address: null requires_memo: false photo_uri: >- https://assets.coingecko.com/coins/images/279/standard/ethereum.png is_monitored: true has_settlement_route: false availability_status: STALE rate_updated_at: 1704109800 unavailable_reason: Rate data is older than 5 minutes devnet: value: - id: 1 token_symbol: USDC token_name: USD Coin token_type: erc20 network: solana token_decimals: 6 token_address: So11111111111111111111111111111111111111112 requires_memo: false photo_uri: >- https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/So11111111111111111111111111111111111111112/logo.png supports_stable_settlement: true is_monitored: null has_settlement_route: false availability_status: DEVNET '400': description: Quote calculation failed content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing/invalid session authentication content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: User or invoice not found content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Too many requests content: application/json: schema: $ref: '#/components/schemas/RateLimitError' '500': description: No settlement tokens available or database error content: application/json: schema: $ref: '#/components/schemas/Error' security: - PaymentSessionToken: [] PaymentSessionSignature: [] components: schemas: Getapiv1paymentsavailable-tokensResponse200: type: array items: $ref: '#/components/schemas/PaymentToken' Error: type: object description: Standard error response (not used for rate limiting). properties: error: type: string description: Human-readable error message. code: type: string nullable: true description: Optional machine-readable error code. details: nullable: true description: >- Optional structured details (present in some development/debug scenarios). oneOf: - type: string - type: object additionalProperties: true - type: array items: type: object additionalProperties: true example: error: Failed to fetch available tokens code: DATABASE_ERROR RateLimitError: type: object description: Rate limit error response (HTTP 429). properties: error: type: string error_code: type: string source: type: string example: error: Too many requests. Please try again in a minute. error_code: PAYMENT_SESSION_RATE_LIMIT source: payment_session PaymentToken: type: object properties: id: type: number description: Token ID token_symbol: type: string description: Token ticker symbol token_name: type: string description: Full token name token_type: type: string enum: - native - erc20 - spl - ton - sui description: Token standard type network: type: string description: Blockchain network token_decimals: type: number description: Token decimal places token_address: type: string nullable: true description: Smart contract address (null for native tokens). requires_memo: type: boolean description: Whether memo is required photo_uri: type: string nullable: true description: Token logo URI when available. has_settlement_route: type: boolean description: Whether settlement path exists supports_stable_settlement: type: boolean nullable: true description: >- Whether this token can be used as a stable settlement token (when applicable). is_monitored: type: boolean nullable: true description: >- Whether this token is monitored for precomputed rates (mainnet only). settlement_rate: type: number nullable: true description: Exchange rate to settlement token settlement_cost_usd: type: number nullable: true description: Total cost in USD after settlement is_same_token_settlement: type: boolean nullable: true description: Whether payment and settlement tokens match tier: type: string nullable: true description: Pricing tier tier_fee: type: number nullable: true description: Tier-based fee amount availability_status: type: string enum: - AVAILABLE - STALE - NO_LIQUIDITY - QUOTE_REQUIRED - DEVNET description: Quote availability status. rate_updated_at: type: integer description: Last rate update timestamp (epoch seconds). unavailable_reason: type: string nullable: true description: >- Present when `has_settlement_route` is false (e.g. no liquidity or stale quote data). securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT token for wallet authentication PaymentSessionToken: type: apiKey in: header name: x-session-token description: >- Payment session token (opaque). Returned when creating an invoice; send on every request. PaymentSessionSignature: type: apiKey in: header name: x-signature description: >- Payment session signature in the format `signature_hash.timestamp_ms` (returned with the invoice/session). ````