빠른 시작
이 가이드를 따라 5분 안에 첫 스테이블코인 결제를 연동해보세요.
사전 요구사항
- Volr Dashboard 계정 및 프로젝트
- Server Key (Dashboard에서 발급)
- Dashboard에서 수락 토큰 설정 (USDC, USDT 등)
- 테스트용 USDC (Base Testnet 또는 Sepolia)
Step 1: Server Key 발 급
- Volr Dashboard에 로그인
- 프로젝트 선택 후 Settings → Security로 이동
- Server Key 복사 (예:
volr_server_xxx...)
Server Key 보안
Server Key는 절대 클라이언트 코드에 노출하면 안 됩니다. 백엔드 서버에서만 사용하세요. 프론트엔드/SDK에서는 API Key (volr_sk_...)를 사용하세요.
Step 2: Checkout 생성
curl -X POST https://api.volr.io/v1/checkouts \
-H "x-api-key: volr_server_xxx" \
-H "Content-Type: application/json" \
-d '{
"fiatAmount": "5000",
"fiatCurrency": "KRW",
"itemName": "아메리카노",
"referenceId": "ORDER-12345"
}'
필수 파라미터
- fiatAmount + fiatCurrency: 법정화폐 금액 (예: "5000" KRW)
- 또는 amount: 토큰 직접 금액 (최소 단위)
토큰과 체인은 생성 시 지정하지 않습니다. 고객이 체크아웃 페이지에서 원하는 토큰 을 선택합니다.
응답
{
"ok": true,
"data": {
"id": "cm5xyz123...",
"chainId": null,
"tokenAddress": null,
"amount": null,
"depositAddress": null,
"status": "PENDING",
"expiresAt": "2026-01-30T11:00:00.000Z",
"fiatAmount": "5000",
"fiatCurrency": "KRW",
"itemName": "아메리카노",
"referenceId": "ORDER-12345"
}
}
Step 3: 고객 토큰 선택
고객을 체크아웃 페이지로 리디렉트하세요. 프로젝트에 설정된 수락 토큰 중에서 원하는 스테이블코인과 체인을 선택합니다.
https://checkout.volr.io/c/{checkoutId}
토큰 선택 후 depositAddress가 생성되고 결제 UI가 표시됩니다.
Step 4: 결제 확인
Webhook (선택)
Dashboard에서 Webhook URL을 설정하면 결제 완료 시 자동으로 알림을 받습니다.
{
"event": "checkout.paid",
"data": {
"checkoutId": "cm5xyz123...",
"status": "PAID",
"fiatAmount": "5000",
"fiatCurrency": "KRW",
"exchangeRateUsed": "1350.50",
"paymentTxHash": "0xdef456...",
"referenceId": "ORDER-12345"
}
}