CoinVoyage integration flows

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.

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.

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.

Best for

Wallet funding, app balances, gaming accounts, trading accounts, and user-controlled deposits.

PayOrder mode

DEPOSIT

Flow

Collect the destination

Ask the user which supported chain and destination address they want to receive funds on.

Create a Deposit PayOrder

Create a DEPOSIT PayOrder with the destination chain, destination token, amount, and receiving address.

Open the payment modal

Render PayButton or pass the generated payId to your own checkout UI.

Track completion

Listen for payorder_completed, payorder_expired, payorder_refunded, and payorder_error events.

<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, PayButton, and PayOrders.

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.

Best for

Ecommerce checkout, SaaS billing, travel bookings, digital goods, and service payments.

PayOrder mode

SALE

Flow

Create an internal order

Create the order in your backend first and store the amount, currency, customer, and line items.

Create a Sale PayOrder on the server

Use ApiClient.createSalePayOrder() with your API secret. Include your internal order ID in metadata.

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.

Fulfill from webhooks

Fulfill the order after your backend receives and verifies payorder_completed.

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, API overview, Webhooks, and 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.

Best for

Wallet rebalancing, pre-funding a payment asset, treasury operations, and custom swap UI.

API methods

swapQuote(), swapData()

Flow

Collect swap intent

Ask the wallet owner for the source asset, destination asset, amount, sender address, and acceptable slippage.

Get a swap quote

Call ApiClient.swapQuote() with the source and destination details so the user can review the expected output and route.

Get execution data

Call ApiClient.swapData() for the selected quote or route to retrieve the transaction data required for execution.

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.

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, Supported networks, and 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.

Best for

Treasury operations, creator payouts, merchant fiat settlement, and finance-team withdrawals.

API areas

KYC, bank accounts, withdrawals

Flow

Complete KYC or KYB

Create a hosted verification link with ApiClient.createKYCLink() and check the organization’s verification status with ApiClient.getKYCStatus().

Add a bank account

Add the payout destination with ApiClient.addBankAccount(), then use listBankAccounts() or getBankAccount() when an operator selects where funds should go.

Create a withdrawal

Call ApiClient.createWithdrawal() from your server with the source currency, linked bank account details, payment rail, and sender wallet address.

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.

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 to choose the correct fiat rail and recipient fields before adding bank-account forms.

Read next: ApiClient, API overview, Supported regions, and Withdrawals.

Example 5: Send no-code payment invoices

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

Best for

Manual invoices, sales-assisted deals, professional services, B2B payments, and one-off payment links.

Interface

CoinVoyage Dashboard

Flow

Create the invoice

Open the dashboard, enter the customer, amount, due date, and line items, then generate the payment link.

Send the payment request

Email the invoice from the dashboard or copy the payment link into your own customer communication.

Customer pays with crypto

The customer opens the link, chooses a supported chain and token, and completes the payment.

Reconcile the invoice

Track status in the dashboard and use webhooks if your backend needs to update CRM, ERP, or accounting records.

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, Transactions, and 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.

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

Flow

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.

Select an acceptable payment requirement

Use @coin-voyage/paykit-headless to decode the challenge and choose a supported chain, network, asset, and amount.

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.

Documentation Index

​Flow map

​Example 1: Let users deposit to their own wallet

Best for

PayOrder mode

​Flow

​Implementation notes

​Example 2: Accept merchant checkout payments

Best for

PayOrder mode

​Flow

​Implementation notes

​Example 3: Swap between supported assets

Best for

API methods

​Flow

​Implementation notes

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

Best for

API areas

​Flow

​Implementation notes

​Example 5: Send no-code payment invoices

Best for

Interface

​Flow

​Implementation notes

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

​Flow

Flow map

Example 1: Let users deposit to their own wallet

Flow

Implementation notes

Example 2: Accept merchant checkout payments

Flow

Implementation notes

Example 3: Swap between supported assets

Flow

Implementation notes

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

Flow

Implementation notes

Example 5: Send no-code payment invoices

Flow

Implementation notes

Example 6: Pay protected resources with x402 (Preview)

Flow