REST API 레퍼런스

FakeToss 서버는 `https://faketoss-alpha.yjroot.kr/v1/*` 아래에서 동작합니다. 모든 서버 호출은 Secret Key 기반 Basic Auth를 사용합니다.

Basic Auth / Idempotency-Key

인증 헤더는 `Authorization: Basic base64(secretKey:)` 형식입니다. 재시도 가능성이 있는 승인 API에는 `Idempotency-Key`를 함께 보내 중복 처리를 방지하세요.

const authorization = "Basic " + Buffer.from("test_sk_yjroot_faketoss_default:").toString("base64");

await fetch("https://faketoss-alpha.yjroot.kr/v1/payments/confirm", {
  method: "POST",
  headers: {
    Authorization: authorization,
    "Content-Type": "application/json",
    "Idempotency-Key": "confirm-order-001",
  },
});

POST /v1/payments/confirm

curl -X POST https://faketoss-alpha.yjroot.kr/v1/payments/confirm \
  -H "Authorization: Basic $(printf 'test_sk_yjroot_faketoss_default:' | base64)" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: confirm-order-001" \
  -d '{
    "paymentKey": "pay_123",
    "orderId": "order-001",
    "amount": 15000
  }'

{
  "paymentKey": "pay_123",
  "orderId": "order-001",
  "orderName": "FakeToss 티셔츠",
  "amount": 15000,
  "status": "DONE",
  "approvedAt": "2026-04-21T10:14:00+09:00"
}

GET /v1/payments/{key}

curl -H "Authorization: Basic $(printf 'test_sk_yjroot_faketoss_default:' | base64)" \
  https://faketoss-alpha.yjroot.kr/v1/payments/pay_123

{
  "paymentKey": "pay_123",
  "status": "DONE",
  "method": "CARD",
  "card": { "number": "1234-****-****-5678" }
}

GET /v1/payments/orders/{id}

curl -H "Authorization: Basic $(printf 'test_sk_yjroot_faketoss_default:' | base64)" \
  https://faketoss-alpha.yjroot.kr/v1/payments/orders/order-001

{
  "paymentKey": "pay_123",
  "orderId": "order-001",
  "status": "DONE"
}

POST /v1/payments/{key}/cancel

curl -X POST https://faketoss-alpha.yjroot.kr/v1/payments/pay_123/cancel \
  -H "Authorization: Basic $(printf 'test_sk_yjroot_faketoss_default:' | base64)" \
  -H "Content-Type: application/json" \
  -d '{ "cancelReason": "고객 요청" }'

{
  "paymentKey": "pay_123",
  "status": "CANCELED",
  "cancels": [{ "amount": 15000, "reason": "고객 요청" }]
}

POST /v1/virtual-accounts

curl -X POST https://faketoss-alpha.yjroot.kr/v1/virtual-accounts \
  -H "Authorization: Basic $(printf 'test_sk_yjroot_faketoss_default:' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order-va-001",
    "orderName": "가상계좌 주문",
    "amount": 25000,
    "customerName": "홍길동"
  }'

{
  "paymentKey": "pay_va_123",
  "status": "WAITING_FOR_DEPOSIT",
  "virtualAccount": {
    "bank": "신한",
    "accountNumber": "140-123-456789",
    "dueDate": "2026-04-22T23:59:59+09:00"
  }
}

POST /v1/billing/authorizations/issue

curl -X POST https://faketoss-alpha.yjroot.kr/v1/billing/authorizations/issue \
  -H "Authorization: Basic $(printf 'test_sk_yjroot_faketoss_default:' | base64)" \
  -H "Content-Type: application/json" \
  -d '{ "authKey": "auth_123", "customerKey": "550e8400-e29b-41d4-a716-446655440000" }'

{
  "billingKey": "bill_123",
  "customerKey": "550e8400-e29b-41d4-a716-446655440000",
  "method": "CARD"
}

POST /v1/billing/{billingKey}

curl -X POST https://faketoss-alpha.yjroot.kr/v1/billing/bill_123 \
  -H "Authorization: Basic $(printf 'test_sk_yjroot_faketoss_default:' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "customerKey": "550e8400-e29b-41d4-a716-446655440000",
    "orderId": "billing-order-001",
    "orderName": "월 구독권",
    "amount": 9900
  }'

{
  "paymentKey": "pay_bill_123",
  "status": "DONE",
  "approvedAt": "2026-04-21T11:00:00+09:00"
}

Swagger

엔드포인트를 브라우저에서 탐색하려면 Swagger UI를 여세요. 문서 링크는 `/docs`가 아니라 `/api-docs` 입니다.

/api-docs