본문으로 건너뛰기

Fiat Payment

Volr Checkout API는 원화(KRW) 또는 달러(USD)로 가격을 설정하면 자동으로 스테이블코인 금액을 계산해줍니다.

How It Works​

  1. 가맹점이 원화 가격으로 Checkout 생성 (예: 5,000원)
  2. Volr API가 현재 환율을 조회 (CoinGecko)
  3. 스테이블코인 금액 자동 계산 (예: 3.70 USDC)
  4. 고객이 계산된 금액으로 결제

Supported Currencies​

Fiat CurrencyDescription
KRW대한민국 원화
USD미국 달러

Supported Tokens​

Fiat 변환은 다음 스테이블코인에서만 지원됩니다:

TokenWhy Supported
USDCUSD 페깅 스테이블코인
USDTUSD 페깅 스테이블코인
경고

ETH, MATIC 등 비-스테이블코인은 가격 변동성이 크기 때문에 Fiat 변환을 지원하지 않습니다.

Get Current Exchange Rates​

결제 생성 전에 현재 환율을 확인할 수 있습니다.

Endpoint​

GET /dashboard/projects/{projectId}/checkouts/exchange-rate

Query Parameters​

ParameterTypeRequiredDescription
fiatCurrencystringNoKRW 또는 USD. 미지정 시 모든 환율 반환

Response (특정 통화)​

GET /checkouts/exchange-rate?fiatCurrency=KRW
{
  "ok": true,
  "data": {
    "fiatCurrency": "KRW",
    "rates": {
      "USDC": "1350.50",
      "USDT": "1351.20"
    },
    "timestamp": "2026-01-30T10:30:00.000Z"
  }
}

Response (모든 환율)​

GET /checkouts/exchange-rate
{
  "ok": true,
  "data": {
    "rates": {
      "USDC": {
        "KRW": "1350.50",
        "USD": "1.00"
      },
      "USDT": {
        "KRW": "1351.20",
        "USD": "1.001"
      }
    },
    "timestamp": "2026-01-30T10:30:00.000Z",
    "source": "cache"
  }
}

Create Fiat Checkout​

Request​

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": "아메리카노"
  }'

Response​

{
  "ok": true,
  "data": {
    "id": "cm5xyz123...",
    "amount": "3703703",
    "fiatAmount": "5000",
    "fiatCurrency": "KRW",
    "exchangeRateUsed": "1350.50",
    "exchangeRateAt": "2026-01-30T10:30:00.000Z",
    "expiresAt": "2026-01-30T11:00:00.000Z"
  }
}

Exchange Rate Calculation​

환율 계산 공식:

tokenAmount = fiatAmount / exchangeRate

예시 (5,000원, 환율 1,350.50):

5000 / 1350.50 = 3.7017 USDC
= 3701700 (6 decimals, 소수점 버림)
소수점 처리

토큰 금액은 버림(floor) 처리됩니다. 이는 고객이 과다 지불하지 않도록 하기 위함입니다.

Expiry Time Limit​

Fiat 결제 사용 시 환율 변동 리스크를 줄이기 위해 만료 시간이 최대 30분으로 제한됩니다.

  • expiryMinutes: 60으로 요청해도 자동으로 30분으로 조정됨
  • 일반 토큰 금액 결제(amount)는 최대 1440분(24시간)까지 가능

Error Handling​

EXCHANGE_RATE_UNAVAILABLE​

환율 조회에 실패한 경우:

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

해결 방법: 잠시 후 다시 시도하거나, amount를 직접 지정하세요.

UNSUPPORTED_TOKEN_FOR_FIAT​

스테이블코인이 아닌 토큰에 fiat 결제를 시도한 경우:

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

Best Practices​

1. 환율 미리 조회​

결제 화면에서 예상 금액을 표시하려면 환율을 미리 조회하세요.

const rates = await getExchangeRates('KRW');
const expectedUsdc = (priceKRW / parseFloat(rates.USDC)).toFixed(2);
console.log(`약 ${expectedUsdc} USDC`);

2. 환율 변동 안내​

30분 안에 결제하지 않으면 새 Checkout을 생성해야 한다고 안내하세요.

3. Fallback 처리​

환율 조회 실패 시 고정 환율을 사용하거나 에러 메시지를 표시하세요.

try {
  const checkout = await createFiatCheckout(5000, 'KRW');
} catch (error) {
  if (error.code === 'EXCHANGE_RATE_UNAVAILABLE') {
    // Fallback: 직접 환율 계산
    const fallbackRate = 1350;
    const amount = Math.floor(5000 / fallbackRate * 1e6);
    const checkout = await createTokenCheckout(amount);
  }
}