> ## 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.

# 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:

```mermaid theme={null}
sequenceDiagram
    participant Merchant as Merchant App
    participant CV as CoinVoyage
    participant User as User
    participant Wallet as User Wallet
    participant Providers as Quote Providers
    participant Dest as Destination Wallet

    Note over Merchant,CV: 1. PayOrder Creation
    Merchant->>CV: Create PayOrder (Deposit/Sale/Refund)
    CV-->>Merchant: PayOrder ID and Details
    CV->>Merchant: Webhook: payorder_created
    Merchant->>User: Display Payment Modal

    Note over User,User: 2. Select Payment Method
    User->>User: Select Chain (SUI/BTC/SOL/EVM)
    User->>CV: Send Wallet Address and Chain Type

    Note over CV,Providers: 3. Quote Generation
    CV->>CV: Scan for Token Balances
    CV->>Providers: Request Quotes
    Providers-->>CV: Return All Possible Routes
    CV-->>User: Display Top Quotes

    Note over User,CV: 4. Quote Selection
    User->>CV: Select Preferred Quote
    CV->>CV: Generate Payment Details
    CV-->>User: Deposit Address, Amount, Expiration

    Note over User,CV: 5. Payment Execution
    CV->>Merchant: Webhook: payorder_started
    User->>Wallet: Send Funds to Deposit Address
    Wallet->>CV: Transaction Detected
    CV->>Merchant: Webhook: payorder_confirming
    CV->>CV: Verify Transaction

    Note over CV,Dest: 6. Provider Chain Execution
    CV->>Providers: Execute Route (Provider 1 -> Provider 2 -> ...)
    CV->>Merchant: Webhook: payorder_executing
    Providers->>Dest: Deliver Funds
    Dest-->>CV: Confirm Receipt

    Note over CV,Merchant: 7. Settlement Complete
    CV->>CV: Update PayOrder Status: COMPLETED
    CV->>Merchant: Webhook: payorder_completed
    CV-->>User: Payment Success Notification
```

## Detailed flow steps

<Steps>
  <Step title="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](/v2/concepts/pay-orders) page.

    ```typescript theme={null}
    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",
      },
    });
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.

    <Note>
      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`).
    </Note>
  </Step>

  <Step title="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
  </Step>
</Steps>

## 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:

```text theme={null}
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