API Documentation

Explore the Paymos Merchant API for invoices, token balances, signed webhooks, and withdrawals across 13 supported blockchain networks.

Create a project, issue a Payment key, sign the first invoice request, open Hosted Checkout, and verify the paid webhook end to end.

Follow an invoice from creation through asset selection, payment detection, confirmation, expiry, and the final webhook your system consumes.

Test invoice and withdrawal state changes with dedicated test keys, signed webhooks, and simulation endpoints that move no real funds.

Authenticate every Merchant API request with HMAC-SHA256: required headers, canonical payload construction, timestamps, and replay protection.

Create Payment or Payout API keys, understand their scopes and prefixes, rotate credentials safely, and separate test from live access.

Use the Paymos Merchant API base URL for both test and live requests, select the environment by key prefix, and keep one integration path.

Check which of the 13 blockchain networks support USDT, USDC, USD1, DAI, and gold-backed XAUT before enabling assets in a project.

Handle Merchant API errors consistently: response envelope, HTTP status groups, machine-readable codes, request limits, and retry guidance.

Handle Merchant API failures with stable machine-readable codes, field-level validation details, and documented recovery paths.

Read Paymos server time before signing requests and compensate safely for clock drift.

Create an invoice to accept a crypto payment. Two flows: direct crypto (token and network fixed) and fiat (customer picks the token on the hosted checkout).

List invoices with strict status and date filters, navigate forward with cursor pagination, and reconcile results without duplicate pages.

Lock the selected token and network for a fiat-priced invoice from a custom checkout, then display the returned payment details safely.

Retrieve one invoice by ID, inspect its payment and confirmation state, and reconcile the response with your own external order reference.

Cancel an open invoice before the customer locks an asset, understand the allowed state transition, and handle the cancellation response.

Move a sandbox invoice through a payment outcome and test the same lifecycle and webhooks as a confirmed on-chain transfer.

Create a withdrawal from a token balance to a whitelisted wallet, choose the payout network, sign the request, and track its status.

List withdrawals with strict filters and forward cursor pagination, review destination networks, and reconcile transfer history reliably.

Retrieve a withdrawal by ID, inspect its current state and transaction reference, and reconcile completion with the signed webhook.

Cancel a pending withdrawal before MPC signing begins, understand which states allow cancellation, and process the updated response.

Complete a pending sandbox withdrawal without broadcasting a transaction and verify payout webhooks end to end.

Retrieve available token balances, read amounts by coin rather than source network, and use the result before creating a withdrawal.

Connect Paymos to your backend with signed, environment-isolated webhook endpoints and a complete delivery workflow.

Handle all 13 Paymos webhook event types with explicit resource state and terminal-state semantics.

Read the versioned webhook envelope and the complete invoice or withdrawal resource snapshot in data.

Verify the X-Webhook-Signature header with HMAC-SHA256, compare signatures safely, enforce timestamp rules, and support secret rotation.

Design for 11 webhook delivery attempts over roughly 16 hours, deduplicate repeated events, inspect failures, and replay after recovery.

Exercise the real sandbox invoice and webhook delivery path from the interactive documentation playground.

Install the official Paymos plugin for WooCommerce, connect project credentials securely, test checkout, and update orders by signed webhook.

Add stablecoin payments to WHMCS invoices, connect the preconfigured Paymos package, test the webhook, and keep existing provisioning rules.

Install the official Paymos extension for OpenCart, connect the store without copying secrets, and validate payment status updates in test mode.

Connect Paymos to Easy Digital Downloads, test a stablecoin order, verify signed payment updates, and release files only after confirmation.

Install the official Paymos add-on for CS-Cart and Multi-Vendor, connect a project, verify signed status updates, and test an order before launch.

Install the Paymos module for Magento 2 or Adobe Commerce, connect test and live credentials, and verify the order-to-invoice status flow.

Install the Paymos plugin for Shopware 6, enable it per sales channel, validate signed transaction updates, and switch modes without reinstalling.

Add Paymos to PrestaShop 8 or 9, download a configured module, verify the signed callback, and test the Payment accepted order transition.

Redirect customers to Hosted Checkout or embed the payment page in a restricted iframe, then fulfil orders from the signed confirmation webhook.

Add a configurable Pay button to any web page, choose the amount source and theme, and open Paymos checkout without building a backend form.

Use a project link as an in-person stablecoin terminal on a phone or tablet, enter the amount, show a QR code, and track confirmation.

Use official Paymos Merchant API clients for JavaScript/TypeScript, Python, PHP, Go, .NET, Java, Ruby, and Rust with typed requests and HMAC signing.

Learn how Paymos protects token balances with 2-of-3 MPC signing, HMAC authentication, signed webhooks, SSRF controls, and audit records.