Skip to main content
Use this checklist before switching a CoinVoyage integration to production. It is written for teams that already have a working payment flow in development and are preparing to accept live payments.

​
Credentials

  • COIN_VOYAGE_API_SECRET is available only to backend services, server actions, or API routes.
  • Client-side code uses only the public API key, such as NEXT_PUBLIC_COIN_VOYAGE_API_KEY.

​
Settlement configuration

  • The production organization has at least one settlement currency configured if you plan to use SALE orders.
  • If not using a settlement currency, make sure order generation specifies recipient and currency at all times.
  • Settlement wallet addresses have been checked on the correct chain.
  • It has been confirmed who owns each receiving wallet, and they have access to them.
  • A small live payment has been completed and reconciled before opening the flow to all users.
  • Off-ramp settings, bank details, and KYC or KYB status are complete if you plan to withdraw to fiat.

​
Order creation

  • SALE and REFUND orders are created from server-side code only.
  • Each order stores your internal order, invoice, account, or customer ID in metadata.
  • Your backend stores the CoinVoyage order ID before showing the payment modal.
  • Your integration validates amount, currency, destination chain, and destination address before creating an order.

​
Payment state handling

Your application should handle every outcome and recovery state, not just successful payments.
  • Fulfillment code is idempotent by CoinVoyage order ID.
  • Duplicate webhook deliveries do not create duplicate shipments, credits, or inventory updates.
  • Partial-payment and underpayment cases are visible to support.
  • Pay to Address partial payments remain unfulfilled until additional deposits move the order to COMPLETED.
  • Users can recover from expired payments by creating a new order.

​
Webhooks

  • A production webhook endpoint is configured in the Developers dashboard.
  • The endpoint uses HTTPS.
  • The raw request body is verified with CoinVoyage-Webhook-Signature before parsing or processing.
  • The webhook secret is stored in a server-side secret store.
  • The endpoint returns a 2xx response quickly and moves heavy work to a queue or background job.
  • Event processing is idempotent by event type, delivery timestamp, and CoinVoyage order ID.
  • Unknown event types are logged and acknowledged instead of breaking delivery.
  • Webhook failures trigger alerts.
Treat webhooks as the real-time signal and API reconciliation as the safety net. Do not depend on browser callbacks alone for fulfillment.

​
Monitoring and reconciliation

  • Payment creation, quote generation, webhook receipt, fulfillment, and refund actions are logged with correlation IDs.
  • Dashboards track created, started, confirming, executing, completed, expired, refunded, failed, and partial-payment counts.
  • Alerts exist for webhook verification failures, elevated API errors, delayed settlement, and repeated provider failures.
  • A scheduled reconciliation job compares internal orders against CoinVoyage order status.
  • Reconciliation can safely repair missed webhook updates.
  • Finance can export or inspect transaction records needed for accounting.

​
Final launch review

1

Run one complete production payment

Use a small amount and verify that the order reaches COMPLETED, the destination wallet receives funds, and your application fulfills exactly once.
2

Run one refund

Refund the test payment, confirm the refund transaction, and verify that your internal records link the refund to the original order.
3

Verify webhook recovery

Temporarily disable non-critical webhook processing in a controlled test, then confirm your reconciliation job can repair missed state updates.
4

Rotate credentials

Rotate a non-production key first. Confirm your deployment and rollback process can update credentials without exposing secrets.
After these checks pass, update production traffic gradually and monitor completion rate, error rate, webhook latency, and support tickets during the first live sessions.