Skip to main content

Quick Start

이 가이드를 따라 5분 안에 첫 스테이블코인 결제를 연동해보세요.

Prerequisites​

  • Volr Dashboard 계정 및 프로젝트
  • API Key (Dashboard에서 발급)
  • 테스트용 USDC (Base Testnet 또는 Sepolia)

Step 1: Get API Key​

  1. Volr Dashboard에 로그인
  2. 프로젝트 선택 → Settings → API Keys
  3. API Key 복사 (예: volr_sk_xxx...)
API Key 보안

API Key는 서버 사이드에서만 사용하세요. 클라이언트(브라우저, 앱)에 노출하면 안 됩니다.

Step 2: Create a Checkout​

curl -X POST https://api.volr.io/dashboard/projects/{projectId}/checkouts \
  -H "x-api-key: volr_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": 8453,
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "fiatAmount": "5000",
    "fiatCurrency": "KRW",
    "itemName": "아메리카노",
    "referenceId": "ORDER-12345"
  }'

Response​

{
  "ok": true,
  "data": {
    "id": "cm5xyz123...",
    "chainId": 8453,
    "tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "amount": "3703703",
    "depositAddress": "0xabc123...",
    "status": "PENDING",
    "expiresAt": "2026-01-30T11:00:00.000Z",
    "fiatAmount": "5000",
    "fiatCurrency": "KRW",
    "exchangeRateUsed": "1350.50",
    "exchangeRateAt": "2026-01-30T10:30:00.000Z",
    "itemName": "아메리카노",
    "referenceId": "ORDER-12345"
  }
}

Step 3: Display QR Code​

depositAddress를 QR 코드로 표시합니다. 고객이 이 주소로 스테이블코인을 전송하면 결제가 완료됩니다.

// Node.js + qrcode 라이브러리 예시
const QRCode = require('qrcode');

const qrData = checkout.depositAddress;
const qrImage = await QRCode.toDataURL(qrData);

Step 4: Monitor Payment​

두 가지 방법으로 결제 상태를 확인할 수 있습니다:

Option A: Polling​

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

Option B: Webhook (권장)​

Dashboard에서 Webhook URL을 설정하면 결제 완료 시 자동으로 알림을 받습니다.

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

Complete Example (Node.js)​

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

const app = express();
const API_KEY = process.env.VOLR_API_KEY;
const PROJECT_ID = process.env.VOLR_PROJECT_ID;
const API_BASE = 'https://api.volr.io';

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

  const response = await fetch(
    `${API_BASE}/dashboard/projects/${PROJECT_ID}/checkouts`,
    {
      method: 'POST',
      headers: {
        'x-api-key': API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        chainId: 8453, // Base
        tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC
        fiatAmount: priceKRW.toString(),
        fiatCurrency: 'KRW',
        itemName,
        referenceId: `ORDER-${Date.now()}`,
      }),
    }
  );

  const { data: checkout } = await response.json();
  
  // Generate QR code
  const qrCode = await QRCode.toDataURL(checkout.depositAddress);

  res.json({
    checkoutId: checkout.id,
    depositAddress: checkout.depositAddress,
    amount: checkout.amount,
    qrCode,
    expiresAt: checkout.expiresAt,
  });
});

// 2. Webhook handler
app.post('/webhook/volr', express.json(), (req, res) => {
  const { event, data } = req.body;
  
  if (event === 'checkout.paid') {
    console.log(`Payment received for order ${data.referenceId}`);
    // TODO: 상품 제공 로직
  }

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

app.listen(3000);

Next Steps​