Skip to main content

Quick Start

Follow this guide to integrate your first stablecoin payment in 5 minutes.

Prerequisites​

  • Volr Dashboard account and project
  • Server Key (volr_server_...) - issued from Dashboard
  • Accepted tokens configured in Dashboard (USDC, USDT, etc.)
  • Test USDC (Base Testnet or Sepolia)
API Key vs Server Key

Volr provides two types of keys:

  • API Key (volr_sk_...): For frontend/SDK - user authentication
  • Server Key (volr_server_...): For backend only - checkout creation, refunds

Checkout API requires Server Key. See Authentication for details.

Step 1: Get Server Key​

  1. Log in to Volr Dashboard
  2. Select your project, then go to Settings → Security
  3. Copy your Server Key (e.g., volr_server_xxx...)
Server Key Security

NEVER expose your Server Key in client-side code. It should only be used in your backend server. For frontend/SDK, use the API Key (volr_sk_...) instead.

Step 2: Create a Checkout​

Use the Server API endpoint with your Server Key to create a checkout.

curl -X POST https://api.volr.io/v1/checkouts \
  -H "x-api-key: volr_server_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "fiatAmount": "4.50",
    "fiatCurrency": "EUR",
    "itemName": "Americano",
    "referenceId": "ORDER-12345"
  }'
Required Parameters
  • fiatAmount + fiatCurrency: Amount in fiat currency (e.g., "4.50" EUR)
  • Or amount: Direct token amount in smallest unit

Token and chain are no longer specified at creation. Customers select their preferred token on the checkout page.

Response​

{
  "ok": true,
  "data": {
    "id": "cm5xyz123...",
    "chainId": null,
    "tokenAddress": null,
    "amount": null,
    "depositAddress": null,
    "status": "PENDING",
    "expiresAt": "2026-01-30T11:00:00.000Z",
    "fiatAmount": "4.50",
    "fiatCurrency": "EUR",
    "itemName": "Americano",
    "referenceId": "ORDER-12345"
  }
}

Step 3: Customer Selects Token​

Redirect the customer to the checkout page. They will choose their preferred stablecoin and chain from your project's accepted tokens.

https://checkout.volr.io/c/{checkoutId}

After token selection, the checkout gets a depositAddress and the payment UI appears.

Step 4: Monitor Payment​

You can check payment status in two ways:

Option A: Polling​

curl https://api.volr.io/c/{checkoutId}
{
  "ok": true,
  "data": {
    "id": "cm5xyz123...",
    "status": "PAID",
    "isPaid": true,
    "paymentTxHash": "0xdef456..."
  }
}

Set up a Webhook URL in the Dashboard to receive automatic notifications when payment is complete.

{
  "event": "checkout.paid",
  "data": {
    "checkoutId": "cm5xyz123...",
    "status": "PAID",
    "fiatAmount": "4.50",
    "fiatCurrency": "EUR",
    "exchangeRateUsed": "0.92",
    "paymentTxHash": "0xdef456...",
    "paidAmount": "4891304",
    "referenceId": "ORDER-12345"
  },
  "timestamp": "2026-01-30T10:35:00.000Z"
}

Complete Example (Node.js)​

const express = require('express');
const axios = require('axios');
const QRCode = require('qrcode');

const app = express();
app.use(express.json());

const SERVER_KEY = process.env.VOLR_SERVER_KEY;
const API_BASE = 'https://api.volr.io';

// Axios instance with default headers
const volrApi = axios.create({
  baseURL: API_BASE,
  headers: {
    'x-api-key': SERVER_KEY,
    'Content-Type': 'application/json',
  },
});

// 1. Create checkout
app.post('/create-payment', async (req, res) => {
  const { itemName, priceEUR } = req.body;

  const { data: result } = await volrApi.post('/v1/checkouts', {
    fiatAmount: priceEUR.toString(),
    fiatCurrency: 'EUR',
    itemName,
    referenceId: `ORDER-${Date.now()}`,
  });

  const checkout = result.data;

  // Customer selects token on the checkout page
  res.json({
    checkoutId: checkout.id,
    checkoutUrl: `https://checkout.volr.io/c/${checkout.id}`,
    expiresAt: checkout.expiresAt,
  });
});

// 2. Webhook handler
app.post('/webhook/volr', (req, res) => {
  const { event, data } = req.body;
  
  if (event === 'checkout.paid') {
    console.log(`Payment received for order ${data.referenceId}`);
    // TODO: Deliver the product
  }

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

app.listen(3000);

Next Steps​