Concept mapping: mostly renames
The mental model transfers almost one-to-one, which is why migrations here are days, not months:
- Invoice → invoice. Their create-payment call becomes
POST /v1/payment/invoice(hosted page) orwhite-label(your own UI). Same inputs — amount, currency, order ID, callback URL — with fiat pricing as a first-class field rather than an estimate endpoint. - IPN → signed webhooks. The callback concept survives; the verification changes. IPN's sorted-JSON HMAC ritual becomes an HMAC-SHA512 over the raw body plus a deterministic
event_idfor dedup — your handler gets simpler, not just different. - Status vocabulary. waiting/confirming/finished maps to Waiting/Paying/Paid, with
Underpaidas an explicit state instead of a partially-paid limbo — decide during migration what your order system does with it, because now you'll actually be told. - Payouts. Their payout API maps to
POST /v1/payoutand batches — with per-item idempotency you'll wish you'd had during the last double-payment incident.
What has no equivalent to migrate: account-level KYC gates on features, since there are none, and custody of deposits — settlement lands on your own non-pooled branch and you withdraw on demand, so "how do I get my balance out" stops being a support ticket genre. Fees simplify to a flat 0.4% with the volume math on the comparison page.
The parallel-run pattern
Never cut over blind. The sequence that makes this boring:
- Week 0 — shadow. Sign up (email + password, no approval queue), enable your coins, mint a scoped key, and stand up the new webhook handler alongside the old IPN endpoint. Send yourself real $5 payments; watch them credit.
- Week 1 — split traffic. Route a slice of checkouts (one product, one region, or a percentage) through OrbChain while everything else stays put. Both gateways post to your order system; reconcile the slice daily against the dashboard export.
- Week 2 — flip the default. New checkouts go to the new gateway; keep the old IPN endpoint alive until every in-flight invoice there has resolved or expired. Then retire it.
If you're on WooCommerce, WHMCS, Magento or their siblings, the "handler" step collapses to installing the plugin next to the old one and switching which is active — the platforms tolerate two payment methods coexisting, which is exactly what a parallel run needs.
The pre-cutover checklist
- Webhook HMAC verified against a test event, and your handler dedupes on
event_id. - Underpaid and expired paths mapped to order states (don't inherit the old gateway's silences).
- A real payout executed end-to-end — including the first-payout holding window on fresh accounts, so payday isn't the discovery moment.
- Treasury policy set on day one: Auto Settle and an auto-payout rule, so balances behave from the first sale.
- Old-gateway balance withdrawn and the account wound down once in-flights clear.
Total new code: one webhook handler and one create-payment call — or zero, with a plugin. The step-by-step endpoint mapping lives on the migration page; the same plan works from OxaPay and friends with the names changed.