Skip to content

Documentation

API Documentation

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

API

Authentication
Authenticate every Merchant API request with HMAC-SHA256: required headers, canonical payload construction, timestamps, and replay protection.
API Keys
Create Payment or Payout API keys, understand their scopes and prefixes, rotate credentials safely, and separate test from live access.
Base URL
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.
Error Handling
Handle Merchant API errors consistently: response envelope, HTTP status groups, machine-readable codes, request limits, and retry guidance.
Error Codes
Handle Merchant API failures with stable machine-readable codes, field-level validation details, and documented recovery paths.

General

Server Time
GET
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 Invoice
POST
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
GET
List invoices with strict status and date filters, navigate forward with cursor pagination, and reconcile results without duplicate pages.
Confirm Payment
POST
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.
Get Invoice
GET
Retrieve one invoice by ID, inspect its payment and confirmation state, and reconcile the response with your own external order reference.
Cancel Invoice
POST
Cancel an open invoice before the customer locks an asset, understand the allowed state transition, and handle the cancellation response.
Simulate Invoice Payment
POST
Move a sandbox invoice through a payment outcome and test the same lifecycle and webhooks as a confirmed on-chain transfer.

Withdrawals

Create Withdrawal
POST
Create a withdrawal from a token balance to a recipient wallet, choose the payout network, sign the request, and track its status.
List Withdrawals
GET
List withdrawals with strict filters and forward cursor pagination, review destination networks, and reconcile transfer history reliably.
Get Withdrawal
GET
Retrieve a withdrawal by ID, inspect its current state and transaction reference, and reconcile completion with the signed webhook.
Cancel Withdrawal
POST
Cancel a pending withdrawal before transaction signing begins, understand which states allow cancellation, and process the updated response.
Simulate Withdrawal Completion
POST
Complete a pending sandbox withdrawal without broadcasting a transaction and verify payout webhooks end to end.

Balance

Get Balances
GET
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
POST
Create a reusable deposit identity for one payer, keyed by your own external ID, with one permanent address per supported network.
List Payment Channels
GET
Page through your payment channels newest first with cursor pagination, and filter by project, status or your own external ID.
Retrieve Payment Channel
GET
Read one payment channel with its permanent per-network addresses, the tokens each network currently accepts, and your current fee rates.
Block Payment Channel
POST
Stop attributing new deposits to a payment channel without deleting it, releasing its addresses or affecting payments already received.
Unblock Payment Channel
POST
Resume attributing deposits to a payment channel; the server returns it to active or provisioning depending on whether an address exists.
Poll Channel Deposits
GET
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
GET
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
POST
Drive a sandbox payment-channel deposit through confirming, reorged or confirmed and receive the same webhooks a real on-chain payment produces.

Webhooks

Webhooks
Connect Paymos to your backend with signed, environment-isolated webhook endpoints and a complete delivery workflow.
Webhook events
Handle all 18 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.
Test webhooks
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.
WHMCS Plugin
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.
CS-Cart Plugin
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.8+ or 8.x / 9.x, connect the store in one click, verify the signed callback, and test the Payment accepted order transition.
Paymos for Drupal Commerce
Connect Paymos to Drupal Commerce, choose Sandbox or Live, and set up payment checks, cron, and module removal.

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.
Terminal
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.
Server SDKs
Use official Paymos Merchant API clients for JavaScript/TypeScript, Python, PHP, Go, .NET, Java, Ruby, and Rust with typed requests and HMAC signing.
MCP Server
Connect Claude Code, Cursor, or any MCP client to a local Paymos server and let an agent build your integration with sandbox invoices and simulated payments.