How CoinVoyage routes and settles cross-chain payments

Learn how CoinVoyage routes payments from any chain to your destination — from PayOrder creation through provider chaining to final settlement.

CoinVoyage handles the full complexity of cross-chain payments so you don’t have to. When a user pays, CoinVoyage scans their wallet, fetches quotes from multiple liquidity providers, selects the optimal route, and executes each step in sequence — all the way through to settlement at your destination address. The sections below walk through every stage of that process.

End-to-end payment flow

The sequence diagram below shows every actor and message involved in a complete payment:

Detailed flow steps

1. PayOrder creation

   Your server (or the SDK’s ApiClient) creates a PayOrder specifying the destination chain, asset, and amount. CoinVoyage returns a PayOrder ID and immediately fires a payorder_created webhook. You then pass that ID to the payment modal so the user can begin.

   Three modes are available depending on your use case — Deposit, Sale, and Refund — each described in detail on the Pay orders page.

   const payOrder = await apiClient.createDepositPayOrder({
     intent: {
       asset: {
         chain_id: ChainId.SUI,
         address: null, // null = native token (SUI)
       },
       amount: {
         token_amount: 10, // 10 SUI
       },
       receiving_address: "0xYourWalletAddress",
     },
   });
   
2. Payment method selection

   The user opens the payment modal and picks their preferred chain and token. CoinVoyage supports payment from:

   • SUI — Sui blockchain
   • BTC — Bitcoin
   • SOL — Solana
   • EVM — Ethereum, Arbitrum, Base, Optimism, Polygon, BSC, and more

   Once the user selects a chain, they provide their wallet address so CoinVoyage can scan for available balances.

3. Quote generation

   CoinVoyage builds quotes by:

   1. Scanning wallet balances to identify tokens the user can pay with
   2. Querying providers for live rates — AMMs (Uniswap, Jupiter, Cetus), CCTP for cross-chain USDC, ChangeNow for cross-chain exchanges, and direct same-chain transfers
   3. Optimizing routes by chaining providers together when that yields a better rate
   4. Ranking quotes by best effective output (highest received amount, lowest fees)

   The top quotes are surfaced to the user for selection.

4. Quote selection and payment details

   After the user picks a quote, CoinVoyage generates the exact payment instructions for that route:

   • Deposit address — a unique address generated for this payment
   • Exact amount — the precise token amount to send
   • Expiration time — the payment window, typically 30 minutes
   • Refund address — where funds return if anything goes wrong

   A quote looks like this before the user confirms:

   Pay:            0.05 ETH (Ethereum)
   Receive:        10 SUI (Sui Network)
   Route:          Ethereum → CCTP → Sui
   Fee:            1.5%
   Estimated time: ~30 seconds
   
5. User payment

   The user sends the exact amount to the deposit address from their wallet. CoinVoyage monitors the blockchain for:

   • Transaction submission — the payment has been broadcast
   • On-chain confirmation — the transaction is included in a block
   • Amount verification — the correct amount was received

   Your server receives a payorder_confirming webhook as soon as the transaction is detected.

6. Backend execution

   Once payment is confirmed, CoinVoyage executes the selected route. Routes can involve a single provider or a chain of providers:

   Single-provider flow

   User Payment → Provider → Destination
   Example: SOL → Direct Transfer → SOL (same chain)
   

   Multi-provider chain

   User Payment → Provider 1 → Provider 2 → Destination
   Example: ETH → Uniswap (ETH → USDC) → CCTP → SUI
   

   CoinVoyage handles route execution, error recovery, and real-time status webhooks throughout this stage. If any step fails, an automatic refund is initiated.

   Webhook subscriptions are configured with uppercase ORDER_* identifiers (e.g., ORDER_EXECUTING), but the delivered JSON payload uses lowercase payorder_* values in the type field (e.g., payorder_executing).

7. Settlement and completion

   When funds arrive at the destination address, CoinVoyage marks the PayOrder as COMPLETED and fires the payorder_completed webhook. All relevant transaction hashes are recorded on-chain.

   If execution fails at any point:

   1. An automatic refund is initiated
   2. Funds are returned to the user’s refund address
   3. The PayOrder status changes to REFUNDED
   4. A payorder_refunded webhook is fired

Provider chaining example

CoinVoyage can chain multiple providers together to find the best possible route for a given payment. Here is what that looks like when a user pays with ETH on Ethereum and you want to receive SUI:

Step 1: User pays ETH on Ethereum
   |
Step 2: Uniswap swaps ETH → USDC (on Ethereum)
   |
Step 3: CCTP transfers USDC from Ethereum → Sui
   |
Step 4: Sui DEX swaps USDC → SUI
   |
Step 5: SUI delivered to your wallet

The entire process is:

• Automated — no manual intervention required at any step
• Optimized — the best route is calculated in real time before the user confirms
• Transparent — all fees, routes, and timing are shown to the user upfront
• Fast — typically completes in under 60 seconds