Skip to main content

Quick Start

Create your first stablecoin checkout in 5 minutes.

1. Install & Initialize​

npx create-volr

This runs the setup wizard:

  • Sign in with email (OTP)
  • Connect your receiver wallet
  • Create a project
  • Select accepted tokens (USDC, USDT, etc.)

After setup, you'll have a VOLR_SERVER_KEY in your .env file.

AI IDE Integration​

Use these prompts with your AI coding assistant for fast, guided integration.

Help me integrate Volr Checkout for stablecoin payments into my server.

Context:
- Package: @volr/checkout-sdk
- Docs: https://docs.volr.io/checkout-sdk/intro
- I need to: create checkouts, handle webhooks, process refunds

Requirements:
1. Install @volr/checkout-sdk
2. Create a checkout endpoint (POST /api/checkout)
3. Set up webhook handler (POST /api/webhooks/volr)
4. Verify webhook signatures with HMAC-SHA256
5. Handle checkout.paid and checkout.expired events

Please explore my codebase first, then implement step by step.

Installation​

Install the Volr Checkout SDK:

npm install @volr/checkout-sdk

Create a Checkout​

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

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

// Create a checkout — customer selects token on the checkout page
const checkout = await volr.create({
  fiatAmount: '10.00',
  fiatCurrency: 'USD',
  itemName: 'Premium Plan',
  referenceId: 'order_123',                               // Your order ID
  successUrl: 'https://yoursite.com/success',
  cancelUrl: 'https://yoursite.com/cancel',
});

// Redirect customer to the checkout page
// Customer will choose their preferred stablecoin and chain
const checkoutUrl = `https://checkout.volr.io/c/${checkout.id}`;

Handle Webhooks​

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

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

  // Verify signature
  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':
      await fulfillOrder(event.data.referenceId!);
      break;
    case 'checkout.expired':
      await releaseInventory(event.data.referenceId!);
      break;
  }

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

Test Your Integration​

Use the Volr CLI to verify your setup:

npx create-volr             # If you haven't already set up
volr checkout doctor      # Check configuration
volr checkout create-test # Create test checkout on Base Sepolia

Next Steps​