> ## 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 withdrawals, dashboard invoices, and x402 payments.

Most CoinVoyage payment integrations use the same PayOrder lifecycle. Adjacent operational flows cover swaps, KYC, bank accounts, withdrawals, 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 withdrawals 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 KYC, bank-account, and withdrawal 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` PayOrder       | Public API key                                          |
| Accept checkout payments for your business          | `SALE` PayOrder          | 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 fiat withdrawal | 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="PayOrder 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 PayOrder">
    Create a `DEPOSIT` PayOrder with the destination chain, destination token, amount, and receiving address.
  </Step>

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

  <Step title="Track completion">
    Listen for `payorder_completed`, `payorder_expired`, `payorder_refunded`, and `payorder_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 PayOrder 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 KYC, a linked bank account, or a withdrawal unless you later add a fiat off-ramp experience.

Read next: [Quickstart](/v2/quickstart), [PayButton](/v2/sdk/paybutton), and [PayOrders](/v2/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="PayOrder 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 PayOrder on the server">
    Use `ApiClient.createSalePayOrder()` with your API secret. Include your internal order ID in metadata.
  </Step>

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

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

```typescript theme={null}
const { data, error } = await apiClient.createSalePayOrder(
  {
    intent: {
      amount: {
        fiat: {
          amount: 149,
          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 PayOrder ID.
* Handle `EXPIRED`, `FAILED`, `REFUNDED`, and `PARTIAL_PAYMENT` states so unpaid orders do not remain ambiguous.
* Fiat withdrawal 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 withdrawals.

Read next: [ApiClient](/v2/sdk/apiclient), [API overview](/v2/api/overview), [Webhooks](/v2/webhooks/overview), and [Production checklist](/v2/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 without creating a PayOrder. 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()`, `swapData()`
  </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.swapData()` for the selected quote or route to retrieve the transaction data required for execution.
  </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 do not create a PayOrder or emit PayOrder lifecycle webhooks.
* 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 withdrawals. A swap changes on-chain assets; a withdrawal moves eligible settlement funds to a linked bank account.

Read next: [ApiClient](/v2/sdk/apiclient), [Supported networks](/v2/concepts/supported-networks), and [Pricing](/v2/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 KYC, bank-account, and withdrawal 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">
    KYC, bank accounts, withdrawals
  </Card>
</CardGroup>

### Flow

<Steps>
  <Step title="Complete KYC or KYB">
    Create a hosted verification link with `ApiClient.createKYCLink()` and check the organization's verification status with `ApiClient.getKYCStatus()`.
  </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 a withdrawal">
    Call `ApiClient.createWithdrawal()` from your server with the source currency, linked bank account details, 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 withdrawal status with `listWithdrawals()` and your internal ledger.
  </Step>
</Steps>

### Implementation notes

* KYC, bank account, and withdrawal 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 withdrawal as separate ledger events. A completed PayOrder means funds reached the destination wallet; a completed withdrawal means a later fiat payout finished.
* Use [Supported regions](/v2/concepts/supported-regions) to choose the correct fiat rail and recipient fields before adding bank-account forms.

Read next: [ApiClient](/v2/sdk/apiclient), [API overview](/v2/api/overview), [Supported regions](/v2/concepts/supported-regions), and [Withdrawals](/v2/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](/v2/dashboard/invoices), [Transactions](/v2/dashboard/transactions), and [Pricing](/v2/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](/v2/sdk/paykit-headless).