Code Examples

Practical examples for integrating with the Volr Checkout API using curl and the @volr/checkout-sdk.

Postman Collection

Download the Postman collection for a ready-to-use API playground.

---

curl Examples

All examples use the Server API Key in the X-API-Key header.

export VOLR_SERVER_KEY="volr_server_YOUR_KEY_HERE"
export VOLR_API="https://api.volr.io"

Create a Checkout

curl -X POST "$VOLR_API/v1/checkouts" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $VOLR_SERVER_KEY" \
  -d '{
    "chainId": 8453,
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "merchantAddress": "0xYOUR_WALLET_ADDRESS",
    "amount": "10000000",
    "itemName": "Premium Plan",
    "itemDescription": "Monthly subscription",
    "referenceId": "order_123",
    "expiryMinutes": 30,
    "successUrl": "https://yoursite.com/success",
    "cancelUrl": "https://yoursite.com/cancel"
  }'

Response:

{
  "id": "ck_abc123...",
  "chainId": 8453,
  "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": "10000000",
  "depositAddress": "0x...",
  "status": "PENDING",
  "expiresAt": "2026-02-20T15:30:00.000Z"
}

Create a Checkout with Fiat Amount

curl -X POST "$VOLR_API/v1/checkouts" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $VOLR_SERVER_KEY" \
  -d '{
    "chainId": 8453,
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "merchantAddress": "0xYOUR_WALLET_ADDRESS",
    "fiatAmount": "25.00",
    "fiatCurrency": "USD",
    "itemName": "Concert Ticket",
    "referenceId": "ticket_456"
  }'

List Checkouts

# List all checkouts (default: 20 per page)
curl "$VOLR_API/v1/checkouts" \
  -H "X-API-Key: $VOLR_SERVER_KEY"

# Filter by status
curl "$VOLR_API/v1/checkouts?status=PAID&take=10" \
  -H "X-API-Key: $VOLR_SERVER_KEY"

# Filter by reference ID
curl "$VOLR_API/v1/checkouts?referenceId=order_123" \
  -H "X-API-Key: $VOLR_SERVER_KEY"

Get a Checkout

curl "$VOLR_API/v1/checkouts/CHECKOUT_ID" \
  -H "X-API-Key: $VOLR_SERVER_KEY"

Cancel a Checkout

curl -X POST "$VOLR_API/v1/checkouts/CHECKOUT_ID/cancel" \
  -H "X-API-Key: $VOLR_SERVER_KEY"

Create a Refund

curl -X POST "$VOLR_API/v1/checkouts/CHECKOUT_ID/refunds" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $VOLR_SERVER_KEY" \
  -d '{
    "amount": "10000000",
    "reason": "Customer requested refund",
    "refundType": "CANCELLATION"
  }'

List Refunds

curl "$VOLR_API/v1/checkouts/CHECKOUT_ID/refunds" \
  -H "X-API-Key: $VOLR_SERVER_KEY"

---

SDK Examples

Installation

npm install @volr/checkout-sdk

Initialize the Client

import { VolrCheckout } from '@volr/checkout-sdk';

const volr = new VolrCheckout({
  serverKey: process.env.VOLR_SERVER_KEY!,
});

Create a Checkout

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

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

List and Filter Checkouts

// List recent paid checkouts
const paidCheckouts = await volr.list({
  status: 'PAID',
  take: 50,
});

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

Handle Webhooks

import { VolrCheckout, type WebhookPayload } from '@volr/checkout-sdk';

// Express.js example
app.post('/webhook/volr', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.headers['x-volr-signature'] as string;
  const payload = req.body.toString();

  const isValid = await VolrCheckout.verifySignature(
    payload,
    signature,
    process.env.VOLR_WEBHOOK_SECRET!,
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  const event: WebhookPayload = JSON.parse(payload);

  switch (event.event) {
    case 'checkout.paid':
      // Fulfill the order
      await fulfillOrder(event.data.referenceId!, event.data.paymentTxHash!);
      break;
    case 'checkout.expired':
      // Release reserved inventory
      await releaseInventory(event.data.referenceId!);
      break;
  }

  res.status(200).send('OK');
});

Process Refunds

// Create a refund
const refund = await volr.createRefund(checkout.id, {
  amount: '5000000',  // Partial refund: 5 USDC
  reason: 'Item out of stock',
  refundType: 'CANCELLATION',
});

// List refunds for a checkout
const refunds = await volr.listRefunds(checkout.id);

---

Common Token Addresses

Token	Chain	Address
USDC	Base (8453)	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
USDT	Base (8453)	0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2
USDC	Polygon (137)	0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359
USDT	Polygon (137)	0xc2132D05D31c914a87C6611C10748AEb04B58e8F
USDC	Arbitrum (42161)	0xaf88d065e77c8cC2239327C5EDb3A432268e5831

Checkout Statuses

Status	Description
PENDING	Awaiting payment
DETECTED	Payment transaction detected on-chain
PAID	Payment confirmed
SETTLED	Funds settled to merchant
EXPIRED	Checkout expired without payment
LATE_PAID	Payment received after expiry
CANCELLED	Checkout was cancelled
REFUNDED	Payment was refunded