Create Checkout

Checkout을 생성하여 결제를 요청합니다.

Endpoint

POST /dashboard/projects/{projectId}/checkouts

Headers

Header	Required	Description
x-api-key	Yes	Your API Key
Content-Type	Yes	application/json

Request Body

Token Amount (직접 지정)

{
  "chainId": 8453,
  "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": "10000000",
  "itemName": "아메리카노",
  "referenceId": "ORDER-12345"
}

Fiat Amount (원화/달러 가격)

{
  "chainId": 8453,
  "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "fiatAmount": "5000",
  "fiatCurrency": "KRW",
  "itemName": "아메리카노",
  "referenceId": "ORDER-12345"
}

Parameters

Parameter	Type	Required	Description
chainId	number	Yes	체인 ID (예: 8453=Base, 42161=Arbitrum)
tokenAddress	string	Yes	ERC-20 토큰 주소 (소문자 변환됨)
amount	string	Conditional	토큰 금액 (최소 단위, wei). fiatAmount 미사용 시 필수
fiatAmount	string	Conditional	법정화폐 금액 (예: "5000"). amount 미사용 시 필수
fiatCurrency	string	Conditional	법정화폐 종류. fiatAmount 사용 시 필수. KRW 또는 USD
amountMode	string	No	금액 모드. FIXED (기본), MINIMUM, OPEN
minAmount	string	No	최소 금액 (MINIMUM 모드)
maxAmount	string	No	최대 금액
expiryMinutes	number	No	만료 시간(분). 기본 30분, 최대 1440분. Fiat 결제 시 최대 30분
customerEmail	string	No	고객 이메일
customerName	string	No	고객 이름
itemName	string	No	상품명
itemDescription	string	No	상품 설명
itemImageUrl	string	No	상품 이미지 URL
referenceId	string	No	클라이언트 주문 ID (중복 방지용 unique key)
metadata	object	No	커스텀 메타데이터 (JSON)
successUrl	string	No	결제 성공 시 리다이렉트 URL
cancelUrl	string	No	결제 취소 시 리다이렉트 URL

Response

Success (201 Created)

{
  "ok": true,
  "data": {
    "id": "cm5xyz123abc",
    "projectId": "project_id",
    "chainId": 8453,
    "tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "amount": "3703703",
    "amountMode": "FIXED",
    "depositAddress": "0xabc123def456...",
    "salt": "0x...",
    "merchantAddress": "0xmerchant...",
    "feeBps": 50,
    "fixedFeeAmount": "0",
    "status": "PENDING",
    "expiresAt": "2026-01-30T11:00:00.000Z",
    "createdAt": "2026-01-30T10:30:00.000Z",
    "updatedAt": "2026-01-30T10:30:00.000Z",
    "itemName": "아메리카노",
    "referenceId": "ORDER-12345",
    "fiatAmount": "5000",
    "fiatCurrency": "KRW",
    "exchangeRateUsed": "1350.50",
    "exchangeRateAt": "2026-01-30T10:30:00.000Z"
  }
}

Error Responses

Missing Amount

{
  "ok": false,
  "error": {
    "code": "AMOUNT_OR_FIAT_REQUIRED",
    "message": "Either amount or fiatAmount must be provided"
  }
}

Unsupported Token for Fiat

{
  "ok": false,
  "error": {
    "code": "UNSUPPORTED_TOKEN_FOR_FIAT",
    "message": "Token ETH is not supported for fiat conversion. Supported: USDC, USDT"
  }
}

Exchange Rate Unavailable

{
  "ok": false,
  "error": {
    "code": "EXCHANGE_RATE_UNAVAILABLE",
    "message": "Unable to fetch exchange rate. Please try again later."
  }
}

Supported Chains & Tokens

Mainnet

Chain	Chain ID	Supported Tokens
Base	8453	USDC, USDT
Arbitrum	42161	USDC, USDT
Polygon	137	USDC, USDT

USDC Token Addresses

Chain	Address
Base	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Arbitrum	0xaf88d065e77c8cC2239327C5EDb3A432268e5831
Polygon	0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359

Examples

cURL

curl -X POST https://api.volr.io/dashboard/projects/PROJECT_ID/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"
  }'

Node.js

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

  const { ok, data, error } = await response.json();
  
  if (!ok) {
    throw new Error(error.message);
  }
  
  return data;
};

Python

import requests

def create_checkout(price_krw: int, item_name: str):
    response = requests.post(
        f"https://api.volr.io/dashboard/projects/{PROJECT_ID}/checkouts",
        headers={
            "x-api-key": API_KEY,
            "Content-Type": "application/json",
        },
        json={
            "chainId": 8453,
            "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
            "fiatAmount": str(price_krw),
            "fiatCurrency": "KRW",
            "itemName": item_name,
            "referenceId": f"ORDER-{int(time.time())}",
        },
    )
    
    result = response.json()
    
    if not result["ok"]:
        raise Exception(result["error"]["message"])
    
    return result["data"]