Developer guide
CoinPayments API Status Mapping for Orders
Map CoinPayments API and callback states to internal order statuses for checkout, fulfillment, customer support, and accounting.
CoinPayments API status mapping is the practice of translating gateway payment events into internal order states that your store can fulfill, pause, refund, or investigate. Good mapping prevents duplicate fulfillment and confusing customer messages.
Key takeaways
- Keep gateway statuses separate from internal order statuses.
- Make callbacks idempotent so repeated events do not duplicate fulfillment.
- Never downgrade a paid order because an older pending event arrives late.
- Give support staff readable status labels and next actions.
Recommended internal statuses
Use a small internal vocabulary: awaiting payment, confirming, paid, expired, underpaid, overpaid, refund pending, manual review, and cancelled. Map gateway-specific events into these names.
Support visibility
Support should see the gateway reference, selected asset, expected amount, received amount, confirmation state, and the next recommended action. Without that context, every issue becomes an engineering escalation.
Accounting visibility
Accounting needs dates, amounts, asset symbols, settlement records, and refund notes. Store these fields in a format that can be exported without copying from screenshots.
Final note
Status mapping is boring infrastructure, which is exactly why it matters. The integration is healthier when the gateway can be swapped without rewriting fulfillment logic.