CoinVoyage integration flows

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.

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.

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.

Best for

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

Order mode

DEPOSIT

Flow

Collect the destination

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

Create a Deposit order

Create a DEPOSIT order with the destination chain, destination token, amount, and recipient address.

Open the payment modal

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

Track completion

Listen for ORDER_COMPLETED, ORDER_EXPIRED, ORDER_REFUNDED, and ORDER_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 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, PayButton, and 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.

Best for

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

Order 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 order on the server

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

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.

Fulfill from webhooks

Fulfill the order after your backend receives and verifies ORDER_COMPLETED.

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, 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. 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(), swapExecute()

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.swapExecute() to create the payment instructions required to fund and execute the swap.

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 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, 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 off-ramp verification, bank-account, and off-ramp intent 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

Verification, bank accounts, off-ramp intents

Flow

Complete KYC or KYB

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

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

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.

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

Get started

Core concepts

Flows

Invoices

PAY

SWAP

API

Webhooks

Dashboard

Guides

Resources

CoinVoyage integration flows

Flow map

Example 1: Let users deposit to their own wallet

Best for

Order mode

Flow

Implementation notes

Example 2: Accept merchant checkout payments

Best for

Order 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

Best for

Order mode

​Flow

​Implementation notes

​Example 2: Accept merchant checkout payments

Best for

Order 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