Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.coinvoyage.io/llms.txt

Use this file to discover all available pages before exploring further.

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 pay-order generation specifies a receiving_address and asset at all time.
  • 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.

​
PayOrder creation

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

​
Payment state handling

Your application should handle every terminal state, not just successful payments.
StateRequired handling
COMPLETEDFulfill the order, credit the account, mark the invoice paid, or release access.
EXPIREDMark the checkout attempt expired and let the user start a new payment.
REFUNDEDRecord the refund transaction and notify the user or operator.
FAILEDKeep the order unpaid and send the case to support or automated recovery.
PARTIAL_PAYMENTPause fulfillment and route the case to a manual or automated resolution flow.
  • Fulfillment code is idempotent by PayOrder ID.
  • Duplicate webhook deliveries do not create duplicate shipments, credits, or inventory updates.
  • Partial-payment and underpayment cases are visible to support.
  • Users can recover from expired payments by creating a new PayOrder.

​
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 ID and PayOrder 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 PayOrder 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 PayOrder 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 PayOrder.
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.