빠른 시작

5분 만에 첫 스테이블코인 체크아웃을 만들어보세요.

1. 설치 및 초기화

npx create-volr

설정 위저드가 실행됩니다:

• 이메일로 로그인 (OTP 인증)
• 수신 지갑 연결
• 프로젝트 생성
• 허용 토큰 선택 (USDC, USDT 등)

설정이 완료되면 .env 파일에 VOLR_SERVER_KEY가 저장됩니다.

AI IDE 연동

AI 코딩 어시스턴트에서 아래 프롬프트를 사용하여 빠르고 정확하게 연동하세요.

Claude Code

서버에 Volr Checkout 스테이블코인 결제를 연동해주세요.

컨텍스트:
- 패키지: @volr/checkout-sdk
- 문서: https://docs.volr.io/checkout-sdk/intro
- 필요한 것: 체크아웃 생성, 웹훅 처리, 환불 처리

요구사항:
1. @volr/checkout-sdk 설치
2. 체크아웃 엔드포인트 생성 (POST /api/checkout)
3. 웹훅 핸들러 설정 (POST /api/webhooks/volr)
4. HMAC-SHA256으로 웹훅 서명 검증
5. checkout.paid와 checkout.expired 이벤트 처리

코드베이스를 먼저 탐색한 후 단계별로 구현해주세요.

Cursor

# Volr Checkout 연동

스테이블코인 체크아웃 결제를 연동해야 합니다.

## 프로젝트 컨텍스트
- 서버 사이드 연동, @volr/checkout-sdk 사용
- 문서: https://docs.volr.io/checkout-sdk/intro

## 요구사항
1. @volr/checkout-sdk 설치
2. 금액, 토큰, 체인으로 체크아웃 엔드포인트 생성
3. 웹훅 알림 처리 (checkout.paid, checkout.expired)
4. 웹훅 서명 검증 (HMAC-SHA256, X-Volr-Signature 헤더)
5. 주문 대조를 위한 체크아웃 참조 저장

## 중요
- 서버 API 키 (volr_server_...) 사용 — 클라이언트 코드에 노출 금지
- Base Sepolia에서 프로덕션 전 테스트

설치

Volr Checkout SDK를 설치합니다:

npm

npm install @volr/checkout-sdk

yarn

yarn add @volr/checkout-sdk

pnpm

pnpm add @volr/checkout-sdk

체크아웃 생성

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

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

// 체크아웃 생성 — 고객이 체크아웃 페이지에서 토큰을 선택합니다
const checkout = await volr.create({
  fiatAmount: '10.00',
  fiatCurrency: 'USD',
  itemName: '프리미엄 플랜',
  referenceId: 'order_123',                               // 내부 주문 ID
  successUrl: 'https://yoursite.com/success',
  cancelUrl: 'https://yoursite.com/cancel',
});

// 고객을 체크아웃 페이지로 리디렉트
// 고객이 원하는 스테이블코인과 체인을 선택합니다
const checkoutUrl = `https://checkout.volr.io/c/${checkout.id}`;

웹훅 처리

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

// Express.js 예제
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();

  // 서명 검증
  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');
});

연동 테스트

Volr CLI로 설정을 검증하세요:

npx create-volr             # 아직 설정하지 않았다면 실행
volr checkout doctor      # 설정 확인
volr checkout create-test # Base Sepolia에서 테스트 체크아웃 생성

다음 단계

• Checkout SDK 레퍼런스 — SDK 상세 문서
• 웹훅 가이드 — 웹훅 이벤트와 모범 사례
• 환불 — 환불 처리
• 코드 예제 — curl과 SDK 예제