Skip to content

API

On this page

Overview

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

Paymos sends an HTTPS POST when an invoice or withdrawal changes state. Webhooks are the authoritative asynchronous signal for your backend: API responses start an operation, while webhook events tell you what happened after blockchain processing.

Integration flow

  1. Create a webhook endpoint in Dashboard → Developers → Webhooks.
  2. Choose the Invoice, Withdrawal, or both event categories.
  3. Optionally restrict invoice events to selected projects. Withdrawal events are merchant-wide.
  4. Store the displayed whsec_… secret on your server.
  5. Verify every delivery against the unchanged raw request body.
  6. Persist event_id, acknowledge with 2xx, and process the event asynchronously.

Production and Sandbox have separate endpoints, secrets, and events. A sandbox event is never delivered to a production endpoint.

Endpoint rules

  • The URL must use HTTPS.
  • Up to 10 endpoints can be configured per merchant and environment.
  • The same active URL cannot be registered twice in one environment.
  • An endpoint must subscribe to at least one category.
  • No invoice project filter means every invoice project is included.
  • Suspending or deleting an endpoint stops new deliveries to it.

Delivery headers

Header Contract
Content-Type application/json; charset=utf-8
X-Webhook-Id Stable evt_… identifier; unchanged across retries and manual replay
X-Webhook-Timestamp Unix seconds for this delivery attempt
X-Webhook-Signature t={timestamp},v1={hmac_hex}; may contain two v1 values during rotation

Delivery is at-least-once and ordering is not guaranteed. Deduplicate by X-Webhook-Id, then apply the resource state from data instead of counting events or assuming arrival order.

Webhook documentation

Get Balances Webhook events