# Pepay

## Docs

- [Simulate a Commerce order transition (devnet only)](https://docs-alpha.pepay.io/api-reference/commerce--devnet-simulator/simulate-a-commerce-order-transition-devnet-only.md): Advances a **devnet** commerce order to a specific state for integration testing.
- [Check commerce service status](https://docs-alpha.pepay.io/api-reference/commerce--general/check-commerce-service-status.md): Check if commerce features are available and properly configured. This endpoint verifies: - Commerce feature flag is enabled - Escrow account has sufficient balance - External commerce services are properly configured
- [Get commerce service information](https://docs-alpha.pepay.io/api-reference/commerce--general/get-commerce-service-information.md): Retrieve information about the commerce service including: - Supported retailers and features - Service limits and constraints - Fee structure
- [Delete a merchant address](https://docs-alpha.pepay.io/api-reference/commerce--merchant-addresses/delete-a-merchant-address.md): Delete a saved address scoped to the authenticated merchant.
- [List merchant addresses](https://docs-alpha.pepay.io/api-reference/commerce--merchant-addresses/list-merchant-addresses.md): Retrieve saved addresses scoped to a merchant. Provide either `customer_id` OR (`wallet_address` + `wallet_network`).
- [Add item to cart](https://docs-alpha.pepay.io/api-reference/commerce--merchant-cart/add-item-to-cart.md): Add a product to customer's cart or update quantity if already exists
- [Calculate cart totals](https://docs-alpha.pepay.io/api-reference/commerce--merchant-cart/calculate-cart-totals.md): Get cart subtotal, shipping, tax, fees, and total
- [Clear cart](https://docs-alpha.pepay.io/api-reference/commerce--merchant-cart/clear-cart.md): Remove all items from customer's cart
- [Create or initialize cart](https://docs-alpha.pepay.io/api-reference/commerce--merchant-cart/create-or-initialize-cart.md): Create a new cart for a customer, optionally with an initial item
- [Get customer's cart](https://docs-alpha.pepay.io/api-reference/commerce--merchant-cart/get-customers-cart.md): Retrieve cart contents for a customer identified by wallet or customer_id
- [Remove item from cart](https://docs-alpha.pepay.io/api-reference/commerce--merchant-cart/remove-item-from-cart.md): Remove a specific item from customer's cart
- [Update cart item quantity](https://docs-alpha.pepay.io/api-reference/commerce--merchant-cart/update-cart-item-quantity.md): Update the quantity of a specific item in customer's cart
- [Validate cart items](https://docs-alpha.pepay.io/api-reference/commerce--merchant-cart/validate-cart-items.md): Check cart items for availability and current prices
- [Get detailed product information](https://docs-alpha.pepay.io/api-reference/commerce--products/get-detailed-product-information.md): Retrieve comprehensive details for a specific product including full description, specifications, images, pricing, availability, and customer reviews.
- [Get product pricing and offers](https://docs-alpha.pepay.io/api-reference/commerce--products/get-product-pricing-and-offers.md): Retrieve current pricing offers for a product including seller information, shipping options, and availability. Results are sorted by best value.
- [Search for products](https://docs-alpha.pepay.io/api-reference/commerce--products/search-for-products.md): Search for products across supported retailers using our commerce platform. Results are cached for 5 minutes to improve performance.
- [List events](https://docs-alpha.pepay.io/api-reference/events/list-events.md): Returns canonical `PepayEvent` objects produced by the unified outbox/dispatcher.
- [Retrieve a single event by id](https://docs-alpha.pepay.io/api-reference/events/retrieve-a-single-event-by-id.md): Fetch a single canonical `PepayEvent` by its id (`evt_<ms>-<seq>`).
- [Create an invoice](https://docs-alpha.pepay.io/api-reference/invoices/create-an-invoice.md): Creates a new invoice and returns a payment URL for the checkout/payment session integration. The idempotency key must be a v4 UUID generated on the client side. Optionally set a pass-through settlement address using `receiver_override_*` fields. Example UUID v4 generation in JavaScript: ```javascri…
- [Get async manual verification job status](https://docs-alpha.pepay.io/api-reference/invoices/get-async-manual-verification-job-status.md): Returns the latest manual verification job for the invoice (created via POST). Use this to poll after triggering manual verification.
- [Get invoice totals](https://docs-alpha.pepay.io/api-reference/invoices/get-invoice-totals.md): Retrieve totals for invoices by status (amounts in USD mills).
- [List invoices by customer ID](https://docs-alpha.pepay.io/api-reference/invoices/list-invoices-by-customer-id.md): Retrieve invoices for a specific customer using cursor pagination.
- [List invoices (cursor pagination)](https://docs-alpha.pepay.io/api-reference/invoices/list-invoices-cursor-pagination.md): Retrieve merchant invoices with Stripe-style cursor pagination and filters.
- [Poll invoice status](https://docs-alpha.pepay.io/api-reference/invoices/poll-invoice-status.md): Retrieve the invoice plus the latest payment status for merchant polling.
- [Retrieve invoice details](https://docs-alpha.pepay.io/api-reference/invoices/retrieve-invoice-details.md): Return a single invoice with full metadata fields.
- [Trigger async manual verification for an invoice](https://docs-alpha.pepay.io/api-reference/invoices/trigger-async-manual-verification-for-an-invoice.md): Enqueues a background job that checks for missed payments for the invoice's active payment address (or the requested network if provided). Use GET to poll job status. The worker performs up to 3 attempts (initial + scheduled retries). Rate limited to one request per minute per invoice.
- [Step 1 - Create checkout estimate (Enhanced)](https://docs-alpha.pepay.io/api-reference/merchant-checkout/step-1--create-checkout-estimate-enhanced.md): Creates a checkout estimate with three operational modes:
- [Step 2 - Set shipping address](https://docs-alpha.pepay.io/api-reference/merchant-checkout/step-2--set-shipping-address.md): Sets and validates shipping address for the order. Requires a valid estimate ID from step 1.
- [Step 3 - Create invoice and order](https://docs-alpha.pepay.io/api-reference/merchant-checkout/step-3--create-invoice-and-order.md): Creates the final order and payment invoice. Returns payment session credentials for payment session APIs.
- [Check payment status for an order](https://docs-alpha.pepay.io/api-reference/merchant-payments/check-payment-status-for-an-order.md): Retrieves the payment status and details for a specific order. Requires Commerce API Key authentication. Only returns orders belonging to the authenticated merchant.
- [Check payment status for multiple orders](https://docs-alpha.pepay.io/api-reference/merchant-payments/check-payment-status-for-multiple-orders.md): Retrieves payment status for up to 50 orders at once. Useful for batch status checks.
- [Get merchant default payment return URL](https://docs-alpha.pepay.io/api-reference/merchant-settings/get-merchant-default-payment-return-url.md): Retrieves the merchant-level default return URL used for hosted checkout when an invoice does not supply a `payment_return_url`. If no default is set, `payment_return_url` is null and `payment_return_url_enabled` is false.
- [Update merchant default payment return URL](https://docs-alpha.pepay.io/api-reference/merchant-settings/update-merchant-default-payment-return-url.md): Sets the merchant-level default return URL for hosted checkout. This URL is used when an invoice does not supply a `payment_return_url`. To clear the default, pass `null` or an empty string. Only HTTPS URLs are allowed.
- [Get merchant order details (scoped)](https://docs-alpha.pepay.io/api-reference/orders/get-merchant-order-details-scoped.md): Returns the canonical **merchant-facing** snapshot for a single commerce order.
- [List merchant scoped orders](https://docs-alpha.pepay.io/api-reference/orders/list-merchant-scoped-orders.md): Requires either JWT bearer token OR Commerce API key authentication
- [Request cancellation for a commerce order (merchant scoped)](https://docs-alpha.pepay.io/api-reference/orders/request-cancellation-for-a-commerce-order-merchant-scoped.md): Requests cancellation for a commerce order. This endpoint is idempotent when you provide an `Idempotency-Key`.
- [Resolve a commerce order by invoice id (merchant scoped)](https://docs-alpha.pepay.io/api-reference/orders/resolve-a-commerce-order-by-invoice-id-merchant-scoped.md): Finds the commerce order associated with a given invoice and returns a merchant-safe summary.
- [Allocate a payment address](https://docs-alpha.pepay.io/api-reference/payment-sessions/allocate-a-payment-address.md): Allocates (or rotates) the temporary payment address for this invoice and returns: - the address to pay, - a quote (estimated token amount + exchange rate), and - a short-lived websocket token for realtime payment updates (`/ws/payment`).
- [Check payment status](https://docs-alpha.pepay.io/api-reference/payment-sessions/check-payment-status.md): Poll for current payment status.
- [Get invoice questions](https://docs-alpha.pepay.io/api-reference/payment-sessions/get-invoice-questions.md): Retrieve custom questions configured for the invoice (if any).
- [Get payment session details](https://docs-alpha.pepay.io/api-reference/payment-sessions/get-payment-session-details.md): Returns the invoice context for a payor payment session.
- [List available payment tokens](https://docs-alpha.pepay.io/api-reference/payment-sessions/list-available-payment-tokens.md): Returns the token options a payor can use to pay this invoice.
- [Retrieve customer email](https://docs-alpha.pepay.io/api-reference/payment-sessions/retrieve-customer-email.md): Get the stored customer email address if available
- [Store customer email](https://docs-alpha.pepay.io/api-reference/payment-sessions/store-customer-email.md): Store customer email address for receipt and notification purposes. Email is validated and normalized.
- [Submit form responses](https://docs-alpha.pepay.io/api-reference/payment-sessions/submit-form-responses.md): Submit responses to invoice custom questions (see `GET /api/v1/payments/invoice-questions`).
- [Get current settlement preference and stable token options](https://docs-alpha.pepay.io/api-reference/settlement-management/get-current-settlement-preference-and-stable-token-options.md): Retrieves the merchant's current settlement preference configuration along with their selected stable settlement token and all available stable token options.
- [Update stable settlement token selection](https://docs-alpha.pepay.io/api-reference/settlement-management/update-stable-settlement-token-selection.md): Allows merchants to select their preferred stable coin token for settlements when their settlement preference is set to receive stable coins.
- [Block or unblock a specific token](https://docs-alpha.pepay.io/api-reference/token-management/block-or-unblock-a-specific-token.md): Updates the acceptance status of a specific token for the merchant. If the merchant's policy is not 'selective', it will be updated to 'selective'. If unblocking the last blocked token, the policy returns to `accept_all`. Token IDs must belong to the merchant's network environment (mainnet/devnet).
- [Get all supported tokens and their acceptance status](https://docs-alpha.pepay.io/api-reference/token-management/get-all-supported-tokens-and-their-acceptance-status.md): Retrieves all supported tokens for the merchant's environment and their acceptance status. This endpoint returns the full list; for large catalogs use `GET /api/v1/merchant/tokens/search`. Blocked state is derived from the acceptance policy: - **accept_all**: all tokens are allowed (no blocks). - **…
- [List supported tokens with pagination and filters](https://docs-alpha.pepay.io/api-reference/token-management/list-supported-tokens-with-pagination-and-filters.md): Returns a paginated list of supported tokens plus each token's blocked status for the authenticated merchant. This endpoint is optimized for large token lists.
- [Mint a short-lived ws_token for browser/mobile websocket auth](https://docs-alpha.pepay.io/api-reference/websockets/mint-a-short-lived-ws_token-for-browsermobile-websocket-auth.md)
- [Authentication](https://docs-alpha.pepay.io/api-spec/authentication.md): Auth headers and when to use each auth mode.
- [Commerce APIs](https://docs-alpha.pepay.io/api-spec/commerce/api-keys.md): Commerce search, carts, checkout, orders, and payments.
- [Errors](https://docs-alpha.pepay.io/api-spec/errors.md): Error envelopes, status codes, and debugging guidance.
- [Merchant APIs](https://docs-alpha.pepay.io/api-spec/merchant/api-keys.md): Server-side merchant endpoints for invoices, tokens, events, and settlement.
- [API Overview](https://docs-alpha.pepay.io/api-spec/overview.md): Base URLs, environments, request conventions, and how this reference is scoped.
- [Pagination](https://docs-alpha.pepay.io/api-spec/pagination.md): Cursor pagination conventions for list endpoints.
- [Payor APIs](https://docs-alpha.pepay.io/api-spec/payors/overview.md): Checkout/session endpoints for customer-facing payment flows.
- [Rate Limits](https://docs-alpha.pepay.io/api-spec/rate-limits.md): How to handle rate limiting and safe retries.
- [WebSockets](https://docs-alpha.pepay.io/api-spec/realtime/websockets.md): Realtime streams for merchants, commerce, and payor sessions.
- [WS token](https://docs-alpha.pepay.io/api-spec/realtime/ws-token.md): Mint a short-lived ws_token for browser/mobile websocket auth.
- [Webhook Events](https://docs-alpha.pepay.io/api-spec/webhook-events.md): Event types and payload examples for webhooks.
- [Webhooks](https://docs-alpha.pepay.io/api-spec/webhooks.md): Payload shape, subscriptions, and delivery semantics.
- [Webhook Authentication](https://docs-alpha.pepay.io/api-spec/webhooks-authentication.md): Signature verification for webhook deliveries.
- [Integrate Commerce](https://docs-alpha.pepay.io/guides/integrate-commerce.md): A-to-Z merchant guide for commerce checkout, orders, and fulfillment.
- [Integrate Cross-chain Payments](https://docs-alpha.pepay.io/guides/integrate-cross-chain-payments.md): A-to-Z merchant guide for accepting multi-chain payments with Pepay.
- [Integrate Payments to Embedded Wallets](https://docs-alpha.pepay.io/guides/integrate-embedded-wallets.md): Guide for funding customer embedded wallets using Pepay settlement.
- [Integrate Onramp and Offramp](https://docs-alpha.pepay.io/guides/integrate-onramp-and-offramp.md): A simple guide to Pepay's beta onramp and offramp flow for stablecoin deposits and bank payouts.
- [Manage Wallets](https://docs-alpha.pepay.io/guides/manage-wallets.md): How non-custodial settlement wallets are added and activated.
- [Capabilities](https://docs-alpha.pepay.io/overview/capabilities.md): A practical overview of Pepay's core building blocks.
- [Get Started](https://docs-alpha.pepay.io/overview/get-started.md): Get API keys, run your first request, and reach first success quickly.
- [How It Works](https://docs-alpha.pepay.io/overview/how-it-works.md): A high-level view of Pepay flows for merchants, commerce, and payors.
- [Security](https://docs-alpha.pepay.io/overview/security.md): Key handling, browser safety, and operational best practices.
- [Why Pepay](https://docs-alpha.pepay.io/overview/why-Pepay.md): Why Pepay exists, what it is, and what it delivers.
- [Addresses](https://docs-alpha.pepay.io/sdk/commerce/addresses.md): List and delete merchant-scoped shipping addresses.
- [Commerce API keys](https://docs-alpha.pepay.io/sdk/commerce/api-keys.md): Create, list, and revoke commerce API keys.
- [Checkout](https://docs-alpha.pepay.io/sdk/commerce/checkout.md): Estimate checkout, collect address, and create an invoice for a commerce order.
- [Merchant carts](https://docs-alpha.pepay.io/sdk/commerce/merchant-carts.md): Create and manage merchant carts (server-to-server).
- [Orders](https://docs-alpha.pepay.io/sdk/commerce/orders.md): List, retrieve, and cancel merchant orders.
- [Payments](https://docs-alpha.pepay.io/sdk/commerce/payments.md): Check commerce payment status and bulk status for orders.
- [Products](https://docs-alpha.pepay.io/sdk/commerce/products.md): Retrieve products and offers for commerce checkout.
- [Commerce search](https://docs-alpha.pepay.io/sdk/commerce/search.md): Search products and offers via the commerce API.
- [Commerce status](https://docs-alpha.pepay.io/sdk/commerce/status.md): Check commerce service status and basic info.
- [WebSockets (commerce)](https://docs-alpha.pepay.io/sdk/commerce/websockets.md): Realtime commerce order updates with recovery and filters.
- [Configure](https://docs-alpha.pepay.io/sdk/configure.md): Configure auth, base URLs, retries, and runtime adapters.
- [Install](https://docs-alpha.pepay.io/sdk/install.md): Install the Pepay SDK for Node.js and browser environments.
- [Access](https://docs-alpha.pepay.io/sdk/merchants/access.md): Activate mainnet access and set environment preferences.
- [API Keys](https://docs-alpha.pepay.io/sdk/merchants/api-keys.md): Create, list, and revoke merchant API keys via the SDK.
- [Events (REST)](https://docs-alpha.pepay.io/sdk/merchants/events.md): List and retrieve events, and recover missed events with helper utilities.
- [Invoices](https://docs-alpha.pepay.io/sdk/merchants/invoices.md): Create invoices, list with filters, retrieve details, and track status.
- [Return URL](https://docs-alpha.pepay.io/sdk/merchants/return-url.md): Manage the merchant default return URL for hosted checkout.
- [Settlement](https://docs-alpha.pepay.io/sdk/merchants/settlement.md): Read and update merchant settlement preferences.
- [Tokens](https://docs-alpha.pepay.io/sdk/merchants/tokens.md): List supported tokens and block/unblock tokens for your merchant.
- [Wallets](https://docs-alpha.pepay.io/sdk/merchants/wallets.md): Retrieve merchant wallets and active settlement destinations.
- [Webhooks (merchant)](https://docs-alpha.pepay.io/sdk/merchants/webhooks.md): Validate Pepay webhook signatures and handle durable event delivery.
- [WebSockets (merchant)](https://docs-alpha.pepay.io/sdk/merchants/websockets.md): Realtime invoice and payment events with recovery and filters.
- [Pepay SDK Overview](https://docs-alpha.pepay.io/sdk/overview.md): Install, configure, and use the Pepay JavaScript/TypeScript SDK.
- [Available tokens (payor)](https://docs-alpha.pepay.io/sdk/payors/available-tokens.md): List tokens available to a payment session.
- [Customer email](https://docs-alpha.pepay.io/sdk/payors/customer-email.md): Set and retrieve the customer email for a payor session.
- [Payment session (payor)](https://docs-alpha.pepay.io/sdk/payors/payment-session.md): Use browser-safe auth to drive the payor checkout flow.
- [Payment status (payor)](https://docs-alpha.pepay.io/sdk/payors/payment-status.md): Fetch the current payment status for a session.
- [WebSockets (payor)](https://docs-alpha.pepay.io/sdk/payors/websockets.md): Connect to payor session websocket updates.

## OpenAPI Specs

- [openapi.generated](https://docs-alpha.pepay.io/api-reference/openapi.generated.json)
- [openapi](https://docs-alpha.pepay.io/openapi.json)