Documentation

API Documentation

REST API for accepting payments, creating invoices, managing withdrawals, and webhooks — with quick start, authentication, the error format, and a sandbox.

Getting Started

Explore the Paymos Merchant API for invoices, token balances, signed webhooks, and withdrawals to whitelisted wallets on 11 payout networks.

Create a project, test an invoice and signed webhook in Sandbox, then create live credentials and accept a first real mainnet payment.

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.

API

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.

Supported Currencies

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.

General

Measure the offset between your clock and Paymos once, then sign locally. GET /v1/time is public, takes no API key or signature, and returns Unix seconds.

Invoices

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.

Confirm Payment

Confirm the token and network on a fiat- or crypto-priced invoice from your own checkout, then show the deposit address and payment details the call returns.

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.

Simulate Invoice Payment

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

Withdrawals

Create Withdrawal

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

List Withdrawals

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 Withdrawal

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

Simulate Withdrawal Completion

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

Balance

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

Payment channels

Create Payment Channel

Create a reusable deposit identity for one payer, keyed by your own external ID, with one permanent address per supported network.

List Payment Channels

Page through your payment channels newest first with cursor pagination, and filter by project, status or your own external ID.

Retrieve Payment Channel

Read one payment channel with its permanent per-network addresses, the tokens each network currently accepts, and your current fee rates.

Block Payment Channel

Stop attributing new deposits to a payment channel without deleting it, releasing its addresses or affecting payments already received.

Unblock Payment Channel

Resume attributing deposits to a payment channel; the server returns it to active or provisioning depending on whether an address exists.

Poll Channel Deposits

Poll confirmed payment-channel deposits in publication order with a cursor that always advances, so no settled payment is skipped or replayed silently.

Retrieve Channel Deposit

Read one payment-channel deposit in any state, with its frozen fee snapshot, gross fee and net amounts, and its on-chain evidence.

Simulate Channel Deposit

Drive a sandbox payment-channel deposit through confirming, reorged or confirmed and receive the same webhooks a real on-chain payment produces.

Webhooks

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

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

Webhook payloads

Read the versioned webhook envelope and the complete invoice, withdrawal or payment-channel deposit snapshot in data.

Verify signatures

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

Delivery and retries

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.

Plugins

WooCommerce Plugin

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, enable the gateway and connect it without typing a key, test the webhook, and keep existing provisioning rules.

OpenCart Plugin

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

Easy Digital Downloads Plugin

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.

Magento 2 Plugin

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

Shopware 6 Plugin

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

PrestaShop Plugin

Add Paymos to PrestaShop 1.7.6+ or 8.x, connect the store in one click, verify the signed callback, and test the Payment accepted order transition.

Integrations

Hosted Checkout

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

JavaScript Low-Code SDK

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 crypto 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.

Security

How Paymos protects token balances: isolated withdrawal signing, destination whitelists, HMAC authentication, signed webhooks, SSRF controls, and audit trails.