Skip to main content

Installation

Install the Package​

npm install @volr/checkout-sdk

Requirements​

  • Node.js 18 or later
  • A Volr project with a Server API Key

Initialize the Client​

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

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

Configuration Options​

OptionTypeDefaultDescription
serverKeystringrequiredServer API Key (volr_server_...)
baseUrlstringhttps://api.volr.ioAPI base URL
timeoutnumber30000Request timeout in milliseconds

Environment Variables​

Store your keys securely in environment variables:

# .env
VOLR_SERVER_KEY=volr_server_your_key_here
VOLR_WEBHOOK_SECRET=whsec_your_secret_here
caution

Never expose the Server API Key in client-side code. The SDK is designed for server-side use only.

Framework Examples​

Express.js​

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

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

app.post('/api/checkout', express.json(), async (req, res) => {
  const checkout = await volr.create({
    chainId: 8453,
    tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
    merchantAddress: process.env.MERCHANT_WALLET!,
    fiatAmount: req.body.amount,
    fiatCurrency: 'USD',
    itemName: req.body.itemName,
    referenceId: req.body.orderId,
  });

  res.json({ checkoutUrl: `https://checkout.volr.io/${checkout.id}` });
});

Next.js (App Router)​

// app/api/checkout/route.ts
import { VolrCheckout } from '@volr/checkout-sdk';
import { NextRequest, NextResponse } from 'next/server';

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

export async function POST(req: NextRequest) {
  const body = await req.json();

  const checkout = await volr.create({
    chainId: 8453,
    tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
    merchantAddress: process.env.MERCHANT_WALLET!,
    fiatAmount: body.amount,
    fiatCurrency: 'USD',
    itemName: body.itemName,
    referenceId: body.orderId,
  });

  return NextResponse.json({
    checkoutUrl: `https://checkout.volr.io/${checkout.id}`,
  });
}

Error Handling​

The SDK throws VolrApiError for API errors:

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

try {
  const checkout = await volr.create({ /* ... */ });
} catch (error) {
  if (error instanceof VolrApiError) {
    console.error(`API Error ${error.statusCode}: ${error.message}`);
    console.error('Response:', error.responseBody);
  }
}

Next Steps​