Crypto payment gateway migration checklist
Use this checklist when replacing or adding a crypto payment gateway. Keep the old and new flows comparable: order reference, hosted checkout URL, webhook event, status rule, support reference, and finance record.
Migration mapping
| Existing gateway concept | SwapSS Pay concept | Doc |
|---|---|---|
| API credentials | Scoped merchant API key | Authentication |
| Test payment | Sandbox invoice | Test mode |
| Order reference | order_id | Invoices |
| Hosted checkout link | payment_url | Invoices |
| Callback or notification | Signed webhook event | Webhooks |
| Fulfillment state | Invoice payment status | Statuses |
| Finance export | Invoice, webhook, polling, and ledger references | Reconciliation |
| Credential controls | Server-side secrets and key rotation | Security |
Cutover sequence
- Create a test API key and complete one sandbox invoice from checkout to webhook handling.
- Map the existing order reference into
order_idand store the returned invoice ID. - Redirect a test buyer to
payment_urland verify the return path. - Verify webhook signatures and dedupe by event ID before changing order state.
- Reload invoice status before fulfillment, service provisioning, or support resolution.
- Record reconciliation fields before routing a production checkout path to the new flow.
Related docs: quickstart, webhook verification, and idempotency.