홈▸개발문서▸Credits API

Credits API

충전금 잔액 조회 API와 충전금 시스템의 동작 방식을 안내합니다.

모든 Credits API는 인증이 필요합니다. API Key를 Authorization: Bearer <API_KEY> 헤더로 제공하세요.

충전금 잔액 조회

GET/v1/credits

현재 파트너 계정의 충전금 잔액을 조회합니다. API Key의 환경(Sandbox/Live)에 따라 해당 환경의 잔액이 반환됩니다.

curl 예시

bash
curl 'https://api-sandbox.sweetbook.com/v1/credits' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response (200 OK)

json
{
  "success": true,
  "message": "Success",
  "data": {
    "balance": 100000,
    "currency": "KRW",
    "env": "test"
  }
}

응답 필드

필드타입설명
balancenumber현재 충전금 잔액 (원)
currencystring통화 코드 (항상 "KRW")
envstring환경 ("test" 또는 "live")
환경 분리: Sandbox와 Live 환경의 충전금은 완전히 분리되어 있습니다. 사용하는 API Key에 따라 해당 환경의 잔액만 반환됩니다.

충전금 시스템 개요

SweetBook은 선불 충전금 방식으로 도서 제작 비용을 결제합니다. Test 충전금과 실제 충전금은 별도로 관리됩니다.

구분설명충전 방법
Test 충전금파트너 포털에서 직접 원하는 금액을 입력하여 자유롭게 설정/조정 가능파트너 포털
실제 충전금파트너 포털에서 PG 결제를 통해 충전파트너 포털 (PG 결제)
충전금 충전은 파트너 포털에서만 가능합니다. API를 통한 충전 엔드포인트는 제공되지 않습니다.

충전금 사용

충전금은 주문 생성 시 자동으로 차감되며, 주문 취소 시 즉시 환불됩니다.

  • 차감: 주문 생성(POST /orders) 시 총 금액(상품금액 + 배송비 + 포장비, 10% VAT 포함)이 즉시 차감됩니다.
  • 환불: 주문 취소(POST /orders/{orderUid}/cancel) 시 결제 금액이 즉시 충전금으로 환불됩니다.
  • 사전 확인: 주문 생성 전에 GET /credits로 잔액을 확인하는 것을 권장합니다.

잔액 부족 (402 Payment Required)

충전금 잔액이 부족한 상태에서 주문을 생성하면 402 Payment Required 에러가 반환됩니다.

json
{
  "success": false,
  "message": "Insufficient Credit",
  "data": {
    "required": 64400.00,
    "balance": 10000.00,
    "currency": "KRW"
  },
  "errors": ["잔액이 부족합니다. 필요: 64400.00, 잔액: 10000.00"]
}

이 에러가 발생하면 파트너 포털에서 충전금을 충전한 후 다시 시도하세요.

관련 문서