Docs

Production checklist

Run through this before you switch from sandbox to mainnet.

A pre-production checklist drawn from the failure modes the platform sees most often.

API integration#

  • API key is stored in a secret manager — never committed.
  • Every POST /api/invoices sends a unique external_id (see Idempotency).
  • Retries on 5xx use exponential backoff, not a tight loop.
  • Errors log enough context to diagnose without PII leakage.

Webhook handler#

  • Raw body is preserved for signature verification (no JSON middleware upstream of the handler).
  • Signature check uses a constant-time comparator.
  • X-Webhook-ID is used as a dedupe key in persistent storage.
  • Handler returns 2xx in under 1 s — any real work is enqueued.
  • Alerting exists if webhook 4xx rate spikes.

Business logic#

  • Fulfilment happens on invoice.confirmed (and invoice.overpaid with a surplus-handling path), not on confirming.
  • invoice.underpaid triggers a human workflow, not automatic fulfilment.
  • invoice.expired triggers order cancellation on your side.
  • invoice.late_payment routes to a reconciliation queue.

Secrets + rotation#

  • You have a runbook for rotating the API key with zero downtime (deploy new → rotate → restart callers).
  • You have a runbook for rotating the webhook secret — handler accepts both old and new during the grace window, or retries failed deliveries after rotation completes.

Observability#

  • Webhook handler logs invoice_id, status, and X-Webhook-ID per request.
  • Reconciliation job runs daily comparing your invoices against the platform's GET /api/invoices list.
  • You monitor the dashboard's Webhook events tab at least once per release window.

Compliance#

  • Customer-facing ToS and privacy policy reference the crypto payment flow.
  • Your team knows the support escalation path for stuck / underpaid invoices.
  • Fulfilment is gated on invoice.confirmed (or a deliberate invoice.overpaid path), never on earlier states.

See also#