홈▸개발문서▸Credits

충전금 시스템

SweetBook API는 선불 충전금 방식으로 도서 제작 비용을 결제합니다. 충전금 잔액 관리, 비용 계산, 거래 내역 조회 방법을 안내합니다.

개요

충전금은 도서 제작 비용을 선불로 충전하여 사용하는 방식입니다. 주문 생성 시 충전금이 자동으로 차감되며, 주문 취소 시 환불됩니다.

환경 분리: Test(Sandbox)와 Live 환경의 충전금은 완전히 분리되어 있습니다. Test 환경에서 사용한 충전금은 Live 환경에 영향을 주지 않습니다.

충전금 거래 유형

충전금 거래 내역에는 다음과 같은 사유 코드(reason)가 포함됩니다.

CodeName방향설명
1CREDIT_RECHARGE+결제 충전
2CREDIT_GRANT+자동 보상 (가입 보너스 등)
3ORDER_PAYMENT-주문 결제
4ORDER_REFUND+주문 환불
7ORDER_CANCEL_REFUND+파트너 취소 환불

비용 계산

주문 시 차감되는 충전금은 다음 공식으로 계산됩니다.

text
TotalAmount = ProductAmount + ShippingFee + PackagingFee

ProductAmount = UnitPrice * Quantity
  - UnitPrice: BookSpec + 페이지 수에 따라 결정

ShippingFee = 3,500원 / 주문

PackagingFee = 500원 * Quantity
항목설명비고
ProductAmount도서 제작 비용 (단가 x 수량)BookSpec, 페이지 수에 따라 단가 결정
ShippingFee배송비주문당 3,500원 고정
PackagingFee포장비권당 500원
VAT: paidCreditAmount (결제 충전 충전금)에는 10% 부가가치세가 포함되어 있습니다.

API 엔드포인트

잔액 조회

GET /credits/balance로 현재 충전금 잔액을 조회합니다.

bash
curl 'https://api.sweetbook.com/v1/credits/balance' \
  -H 'Authorization: Bearer YOUR_API_KEY'
json
{
  "success": true,
  "message": "Success",
  "data": {
    "paidCreditAmount": 150000,
    "freeCreditAmount": 10000,
    "totalCreditAmount": 160000
  }
}

거래 내역 조회

GET /credits/transactions로 충전금 거래 내역을 조회합니다.

bash
curl 'https://api.sweetbook.com/v1/credits/transactions?limit=10&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'
json
{
  "success": true,
  "message": "Success",
  "data": {
    "total": 25,
    "limit": 10,
    "offset": 0,
    "hasNext": true,
    "items": [
      {
        "reason": 3,
        "reasonName": "ORDER_PAYMENT",
        "amount": -12500,
        "balanceAfter": 147500,
        "description": "주문 결제",
        "createdAt": "2025-01-15T09:30:00Z"
      }
    ]
  }
}

잔액 부족 알림

충전금 잔액이 부족한 상태에서 주문을 생성하면 402 Payment Required 응답이 반환됩니다. 주기적으로 잔액을 확인하고, 잔액이 일정 수준 이하로 떨어지면 충전할 수 있도록 알림을 설정하는 것을 권장합니다.

json
{
  "success": false,
  "message": "Insufficient credits. Required: 12500, Available: 5000",
  "data": null
}

관련 문서