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

# CoinVoyage integration flows

> Choose the right CoinVoyage flow for wallet deposits, merchant checkout, swaps, optional fiat off-ramp payouts, dashboard invoices, and x402 payments.

Most CoinVoyage payment integrations use the same order lifecycle. Adjacent operational flows cover swaps, off-ramp verification, bank accounts, off-ramp intents, and x402 agent payments. Use this page to choose the flow that matches your product before you jump into endpoint-level reference.

<Info>
  Bank-account payouts are optional. You can receive funds in an externally owned account (EOA) or any configured destination wallet and move those funds wherever you want from that wallet. Use the off-ramp verification, bank-account, and off-ramp intent APIs only when you want CoinVoyage to coordinate a fiat payout to a linked bank account.
</Info>

## Flow map

| Goal                                                | Flow                     | Credential boundary                                     |
| --------------------------------------------------- | ------------------------ | ------------------------------------------------------- |
| Let a user fund a wallet or app balance             | `DEPOSIT` order          | Public API key                                          |
| Accept checkout payments for your business          | `SALE` order             | Authorization signature created on the server.          |
| Exchange one supported on-chain asset for another   | Swap                     | Public API key                                          |
| Move settlement funds to a bank account             | Optional off-ramp intent | Authorization signature created on the server.          |
| Send payment links without code                     | Dashboard invoices       | Dashboard operator workflow.                            |
| Pay for protected resources from an agent or server | x402 payments (Preview)  | Agent/server signs the payment with its own wallet key. |

## Example 1: Let users deposit to their own wallet

Use this pattern when a user wants to fund a wallet or account on a destination chain while paying from a different chain or token.

<CardGroup cols={2}>
  <Card title="Best for" icon="wallet">
    Wallet funding, app balances, gaming accounts, trading accounts, and user-controlled deposits.
  </Card>

  <Card title="Order mode" icon="arrow-down-to-line">
    `DEPOSIT`
  </Card>
</CardGroup>

### Flow

<Steps>
  <Step title="Collect the destination">
    Ask the user which supported chain and destination address they want to receive funds on.
  </Step>

  <Step title="Create a Deposit order">
    Create a `DEPOSIT` order with the destination chain, destination token, amount, and recipient address.
  </Step>

  <Step title="Open the payment modal">
    Render `PayButton` or pass the generated `orderId` to your own checkout UI.
  </Step>

  <Step title="Track completion">
    Listen for `ORDER_COMPLETED`, `ORDER_EXPIRED`, `ORDER_REFUNDED`, and `ORDER_ERROR` events.
  </Step>
</Steps>

```tsx theme={null}
<PayButton
  intent="Deposit"
  toChain={ChainId.SUI}
  toAddress="0xDestinationWallet"
  toAmount={10}
  toToken={undefined}
/>
```

### Implementation notes

* `DEPOSIT` can use the public API key because the user-provided destination defines where funds go.
* Store your internal account or session ID in order metadata if the deposit credits an app balance.
* Use webhooks for final crediting. Browser callbacks are useful for UI updates, but they should not be your only fulfillment signal.
* This flow does not require off-ramp verification, a linked bank account, or a fiat payout unless you later add a fiat off-ramp experience.

Read next: [Quickstart](/quickstart), [PayButton](/sdk/paybutton), and [Orders](/concepts/pay-orders).

## Example 2: Accept merchant checkout payments

Use this pattern when your application sells products, bookings, subscriptions, credits, or services and you want settlement to your configured merchant wallet or a specific settlement asset.

<CardGroup cols={2}>
  <Card title="Best for" icon="shopping-cart">
    Ecommerce checkout, SaaS billing, travel bookings, digital goods, and service payments.
  </Card>

  <Card title="Order mode" icon="receipt">
    `SALE`
  </Card>
</CardGroup>

### Flow

<Steps>
  <Step title="Create an internal order">
    Create the order in your backend first and store the amount, currency, customer, and line items.
  </Step>

  <Step title="Create a Sale order on the server">
    Use `ApiClient.createSaleOrder()` with your API secret. Include your internal order ID in metadata.
  </Step>

  <Step title="Pass only the order ID to the client">
    The client renders the payment modal with the server-generated `orderId`. Do not expose the API secret.
  </Step>

  <Step title="Fulfill from webhooks">
    Fulfill the order after your backend receives and verifies `ORDER_COMPLETED`.
  </Step>
</Steps>

```typescript theme={null}
const { data, error } = await apiClient.createSaleOrder(
  {
    amount: "149",
    fiat_unit: "USD",
    metadata: {
      order_id: "order_123",
      customer_id: "customer_456",
    },
  },
  process.env.COIN_VOYAGE_API_SECRET!
);
```

### Implementation notes

* `SALE` must be created server-side because it authorizes settlement to your merchant configuration.
* Make fulfillment idempotent by internal order ID and CoinVoyage order ID.
* Handle `EXPIRED`, `FAILED`, `REFUNDED`, and `PARTIAL_PAYMENT` states so unpaid orders do not remain ambiguous.
* Fiat off-ramp payout is a separate, optional follow-up flow. If you settle to your EOA or another configured wallet, you can move funds directly on-chain without using bank-account payouts.

Read next: [ApiClient](/sdk/apiclient), [API overview](/api/overview), [Webhooks](/webhooks/overview), and [Production checklist](/guides/production-checklist).

## Example 3: Swap between supported assets

Use this pattern when you want a wallet to exchange one supported on-chain asset for another. For checkout and deposit flows, CoinVoyage can route swaps as part of payment execution; use the standalone swap APIs when the swap itself is the user action.

<CardGroup cols={2}>
  <Card title="Best for" icon="repeat">
    Wallet rebalancing, pre-funding a payment asset, treasury operations, and custom swap UI.
  </Card>

  <Card title="API methods" icon="arrow-right-left">
    `swapQuote()`, `swapExecute()`
  </Card>
</CardGroup>

### Flow

<Steps>
  <Step title="Collect swap intent">
    Ask the wallet owner for the source asset, destination asset, amount, sender address, and acceptable slippage.
  </Step>

  <Step title="Get a swap quote">
    Call `ApiClient.swapQuote()` with the source and destination details so the user can review the expected output and route.
  </Step>

  <Step title="Get execution data">
    Call `ApiClient.swapExecute()` to create the payment instructions required to fund and execute the swap.
  </Step>

  <Step title="Sign and submit">
    Have the source wallet sign and submit the returned transaction data, then track the resulting on-chain transaction in your own UI or ledger.
  </Step>
</Steps>

### Implementation notes

* Standalone swaps create an internal `SWAP` order and return payment instructions for funding the swap.
* Treat quotes as time-sensitive. Refresh the quote if the user waits, changes wallets, or changes the source amount.
* Show slippage, fees, source asset, destination asset, and destination chain before the user signs.
* Keep swap execution separate from fiat off-ramp payouts. A swap changes on-chain assets; an off-ramp intent moves eligible settlement funds to a linked bank account.

Read next: [ApiClient](/sdk/apiclient), [Supported networks](/concepts/supported-networks), and [Pricing](/resources/pricing).

## Example 4: Off-ramp settlement funds to a bank account

Use this pattern only when you want CoinVoyage to help move an on-chain settlement balance to fiat through a linked bank account. The off-ramp verification, bank-account, and off-ramp intent APIs belong here because they prepare and execute the optional off-ramp path.

<CardGroup cols={2}>
  <Card title="Best for" icon="landmark">
    Treasury operations, creator payouts, merchant fiat settlement, and finance-team withdrawals.
  </Card>

  <Card title="API areas" icon="key">
    Verification, bank accounts, off-ramp intents
  </Card>
</CardGroup>

### Flow

<Steps>
  <Step title="Complete KYC or KYB">
    Create a hosted verification link with `ApiClient.createOffRampVerification()` and check the organization's verification status with `ApiClient.getOffRampVerificationStatus()`.
  </Step>

  <Step title="Add a bank account">
    Add the payout destination with `ApiClient.addBankAccount()`, then use `listBankAccounts()` or `getBankAccount()` when an operator selects where funds should go.
  </Step>

  <Step title="Create an off-ramp intent">
    Call `ApiClient.createOffRampIntent()` from your server with the source currency, amount, linked bank account ID, withdrawal currency, payment rail, and sender wallet address.
  </Step>

  <Step title="Execute and reconcile">
    If the response includes wallet execution data, have the source wallet sign the required on-chain transaction. Track off-ramp status with `listOffRampIntents()` and your internal ledger.
  </Step>
</Steps>

### Implementation notes

* Off-ramp verification, bank account, and off-ramp intent methods are signed server-side operations. Never expose the API secret to the browser.
* Bank account details must match the verified individual or business profile for the organization.
* Keep payment settlement and fiat payout as separate ledger events. A completed order means funds reached the destination wallet; a completed off-ramp intent means a later fiat payout finished.
* Use [Supported regions](/concepts/supported-regions) to choose the correct fiat rail and recipient fields before adding bank-account forms.

Read next: [ApiClient](/sdk/apiclient), [API overview](/api/overview), [Supported regions](/concepts/supported-regions), and [Withdrawals](/dashboard/withdrawals).

## Example 5: Send no-code payment invoices

Use this pattern when an operator wants to request payment without building a custom checkout flow.

<CardGroup cols={2}>
  <Card title="Best for" icon="file-invoice">
    Manual invoices, sales-assisted deals, professional services, B2B payments, and one-off payment links.
  </Card>

  <Card title="Interface" icon="layout-dashboard">
    CoinVoyage Dashboard
  </Card>
</CardGroup>

### Flow

<Steps>
  <Step title="Create the invoice">
    Open the dashboard, enter the customer, amount, due date, and line items, then generate the payment link.
  </Step>

  <Step title="Send the payment request">
    Email the invoice from the dashboard or copy the payment link into your own customer communication.
  </Step>

  <Step title="Customer pays with crypto">
    The customer opens the link, chooses a supported chain and token, and completes the payment.
  </Step>

  <Step title="Reconcile the invoice">
    Track status in the dashboard and use webhooks if your backend needs to update CRM, ERP, or accounting records.
  </Step>
</Steps>

### Implementation notes

* Invoices are useful when you do not need an embedded checkout or SDK integration.
* Use clear line items and due dates so finance and support can reconcile payments later.
* If invoices need to update an internal system, subscribe to webhook events and store invoice identifiers in metadata.

Read next: [Invoices](/dashboard/invoices), [Transactions](/dashboard/transactions), and [Pricing](/resources/pricing).

## Example 6: Pay protected resources with x402 (Preview)

Use this pattern when an agent, server, or automation flow needs to fetch a protected resource, satisfy an x402 `PAYMENT-REQUIRED` challenge, and retry the request with a `PAYMENT-SIGNATURE` header.

<Warning>
  x402 support is in Preview. Expect supported chains, payload details, and helper APIs to evolve before general availability.
</Warning>

### Flow

<Steps>
  <Step title="Request the protected resource">
    Fetch the resource normally. If payment is required, the server returns a `PAYMENT-REQUIRED` challenge with one or more acceptable payment requirements.
  </Step>

  <Step title="Select an acceptable payment requirement">
    Use `@coin-voyage/paykit-headless` to decode the challenge and choose a supported chain, network, asset, and amount.
  </Step>

  <Step title="Sign and retry">
    Sign the payment payload with the agent or server wallet key and retry the original request with the generated `PAYMENT-SIGNATURE` header.
  </Step>
</Steps>

Read next: [PayKit Headless](/sdk/paykit-headless).