Crypto Payments via REST API: A Production-Ready Guide

A crypto payment REST API lets a merchant backend create an invoice, direct the buyer to a payment experience, and fulfil the order after blockchain confirmation. A production integration is not tied to a sample payload. It rests on four durable contracts: authenticated requests, a stable external order identifier, verified webhooks, and a local order transition that remains correct when delivery is repeated.

Paymos exposes the same Merchant API surface in Sandbox and Production with separate credentials. The API can create, retrieve, and cancel invoices and withdrawals, read balances, simulate supported outcomes in Sandbox, and create public Widget SDK invoices.

What can the Merchant API manage?

The Payment side covers invoice creation, retrieval, and cancellation. It lets a merchant backend connect its own order identifier to a Paymos invoice and then choose the customer-facing integration: Hosted Checkout, an embedded iframe, the Widget SDK, or another interface built around the merchant's order flow.

The Payout side creates, retrieves, and cancels withdrawals, while balance operations expose available asset balances. These capabilities use separate credentials from Payment operations. Sandbox can also simulate supported payment and withdrawal outcomes. Keep each capability behind the smallest credential scope the service needs rather than sharing one secret across checkout, finance, and browser code.

How should API requests be authenticated?

Paymos Merchant API authentication uses HMAC-SHA256. It is not Bearer-token authentication. HMAC binds a request to a shared secret without sending that secret as the credential itself, but the integration still has to protect the secret at rest and during deployment.

Sign requests only on a trusted server. Do not expose a Merchant API secret in JavaScript, a mobile bundle, a public repository, or analytics logs. Payment and Payout credentials are separate, so a checkout service that only creates invoices should not hold a Payout credential. Rotate credentials through a controlled deployment process and keep the previous deployment from continuing to use a retired secret.

How should environments and credentials be separated?

Sandbox and Production use separate credentials with the same API surface. That makes Sandbox useful for validating integration behaviour without sending real blockchain assets, but it does not make the environments interchangeable.

Store environment-specific secrets under different names, keep their base configuration separate, and include the environment in operational logs. A Sandbox service should never receive Production credentials. When the integration moves to real payments, change the environment configuration rather than rewriting business logic. The same rule applies to webhook secrets: the receiver must know which environment produced the event before it changes an order.

How do you create invoices safely across retries?

Generate an external_order_id in the merchant's order system and keep it stable for the lifetime of that order. Paymos uses this caller-supplied value for invoice creation. Reusing the same external order identifier returns the existing invoice instead of creating another one, and there is no separate Idempotency-Key header for this operation.

Persist the relationship between the order and its Paymos invoice. If a connection drops before the caller receives a response, retry with the same external_order_id. Never generate a new value merely because the HTTP attempt changed. The identifier represents the business order, not the network request.

Which checkout surface belongs after invoice creation?

Hosted Checkout provides a responsive page, QR payment, and supported wallet deep links. It can be used as a redirect or embedded in an iframe. The Widget SDK supports static amounts, a JavaScript amount callback, a DOM amount source, and a custom-button flow, with iframe and redirect modes.

Payment Links suit invoices shared directly with a buyer. Official CMS plugins cover WooCommerce, WHMCS, OpenCart, PrestaShop, Magento 2, Shopware 6, CS-Cart, and Easy Digital Downloads. The Host-to-Host product is the right surface when the merchant backend must own order creation, state transitions, and fulfilment while still using a supported Paymos checkout experience.

How should webhook signatures be verified?

Each Paymos webhook uses the X-Webhook-Signature header with the format t={timestamp},v1={hmac_hex}. Recompute the HMAC-SHA256 signature with the configured webhook secret and compare it using a timing-safe equality check. Authentication must happen before the event changes an invoice, order, stock level, or entitlement.

Webhook secret rotation includes a grace period in which signatures from the current and previous secrets can be accepted. Configure the receiver for that transition, then remove the previous secret after the grace period. Do not replace signature verification with an IP allowlist: network origin and message authenticity solve different problems.

What should the receiver do about delivery failures?

One webhook delivery cycle includes 11 attempts. Retry delays grow from one minute to eight hours, and the complete cycle lasts approximately 16 hours. Failed or undeliverable events can be replayed manually after the receiving system recovers.

Build the local order update so the same payment cannot trigger fulfilment twice. Record a durable business reference before granting access, shipping goods, or crediting an account. A repeated notification should find the existing result and stop. Manual replay must follow the same path as automatic delivery, so operators cannot accidentally bypass the repeat-safety rule.

How should Sandbox testing be organised?

Sandbox can simulate supported payment and withdrawal outcomes through the same API surface used in Production. Use it to test successful payments, unsuccessful payments, withdrawal outcomes, signature verification, repeated invoice creation, delivery recovery, and reconciliation without moving real assets.

Keep test fixtures tied to stable external_order_id values so a repeated test describes the same business order. Exercise manual webhook replay and confirm that fulfilment remains single. Before switching environments, verify that the service reads Production credentials only from the Production secret store and that no test callback URL remains configured.

When should the merchant fulfil the order?

Fulfil after the payment satisfies the applicable confirmation policy and the webhook signature verifies. Paymos confirmation requirements depend on the network and payment amount. Smaller payments can require fewer confirmations, while larger payments can require a stronger finality threshold. A fixed settlement time is therefore not part of the integration contract. The confirmation guide explains the underlying risk model.

Apply the project's underpayment tolerance before fulfilment. The default is strict matching at 0%. A payment within the configured tolerance completes for the amount actually received; Paymos does not add the missing amount. Below the threshold, a single-payment invoice becomes underpaid, while a multi-payment invoice can remain open.

What belongs in production hardening?

Keep Payment, Payout, Sandbox, and Production credentials separate. Verify every webhook with HMAC-SHA256 and a timing-safe comparison, plan for the current-and-previous-secret rotation grace period, and make fulfilment repeat-safe. Monitor the 11-attempt delivery cycle and document the manual replay procedure.

Use a public webhook destination. Paymos blocks loopback, private, link-local, CGNAT, and IPv6 ULA addresses and does not follow automatic HTTP redirects. Finally, reconcile Paymos invoice state with the merchant order system. The integration is ready when a timeout, repeated creation request, delayed webhook, manual replay, or underpayment cannot produce an incorrect order outcome.