Create Checkout

Create a checkout session to accept a stablecoin payment.

Basic Checkout

const checkout = await volr.create({
  chainId: 8453,                                          // Base
  tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC
  merchantAddress: '0xYOUR_WALLET',
  amount: '10000000',                                     // 10 USDC (6 decimals)
  itemName: 'Premium Plan',
  referenceId: 'order_123',
});

// Redirect customer
const checkoutUrl = `https://checkout.volr.io/${checkout.id}`;

Fiat-Priced Checkout

Price in fiat currency — the API automatically converts to the equivalent token amount:

const checkout = await volr.create({
  chainId: 8453,
  tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
  merchantAddress: '0xYOUR_WALLET',
  fiatAmount: '25.00',
  fiatCurrency: 'USD',
  itemName: 'Concert Ticket',
  referenceId: 'ticket_456',
});

tip

Use fiatAmount + fiatCurrency so customers see familiar prices. The conversion happens at checkout creation time.

Parameters

Parameter	Type	Required	Description
chainId	number	Yes	EVM chain ID (e.g. 8453 for Base)
tokenAddress	string	Yes	ERC-20 token contract address
merchantAddress	string	Yes	Wallet address to receive payment
amount	string	One of amount/fiatAmount	Token amount in smallest unit
fiatAmount	string	One of amount/fiatAmount	Fiat amount (e.g. "25.00")
fiatCurrency	string	With fiatAmount	Currency code (USD, KRW, etc.)
amountMode	string	No	FIXED (default), MINIMUM, or OPEN
expiryMinutes	number	No	Expiry time, 5–1440 min (default: 30)
itemName	string	No	Product name shown on checkout
itemDescription	string	No	Product description
itemImageUrl	string	No	Product image URL
referenceId	string	No	Your internal order ID
customerEmail	string	No	Customer email for receipts
customerName	string	No	Customer name
metadata	object	No	Arbitrary data (returned in webhooks)
successUrl	string	No	Redirect after payment
cancelUrl	string	No	Redirect on cancel

Checkout Response

interface Checkout {
  id: string;                    // Checkout ID
  chainId: number;
  tokenAddress: string;
  amount: string;                // Token amount in smallest unit
  depositAddress: string;        // Address customer sends payment to
  status: CheckoutStatus;        // PENDING, DETECTED, PAID, etc.
  expiresAt: string;             // ISO 8601 expiry time
  itemName: string | null;
  merchantName: string;
  token: TokenInfo | null;       // Token metadata (symbol, decimals, etc.)
  network: NetworkInfo | null;   // Network metadata
  isPaid: boolean;
  paymentTxHash: string | null;  // Set after payment confirmed
  // ... additional fields
}

List Checkouts

// List all checkouts
const checkouts = await volr.list();

// Filter by status
const paidCheckouts = await volr.list({ status: 'PAID', take: 50 });

// Find by reference ID
const [order] = await volr.list({ referenceId: 'order_123' });

Get a Checkout

const checkout = await volr.get('checkout_id_here');

if (checkout.isPaid) {
  console.log(`Paid via tx: ${checkout.paymentTxHash}`);
}

Cancel a Checkout

Only PENDING checkouts can be cancelled:

await volr.cancel('checkout_id_here');

Checkout Lifecycle

Next Steps

• Webhooks — Get notified when payments are confirmed
• Refunds — Process refunds for paid checkouts