충전금 관리

환경별 충전금 운영 방법, 잔액 확인, 차감/환불 규칙, 모니터링 권장사항을 안내합니다.

Test 충전금 (Sandbox)

Sandbox 환경에서는 파트너 포털의 충전금 관리 메뉴에서 테스트 충전금을 직접 원하는 금액으로 입력할 수 있습니다. 테스트 충전금은 실제 돈이 아니며, 자유롭게 추가/삭제할 수 있습니다.

테스트 충전금이 소진되어도 파트너 포털에서 자유롭게 추가할 수 있습니다. Sandbox 환경의 충전금은 Live 환경과 완전히 분리되어 있습니다.

Real 충전금 (Live)

Live 환경에서는 파트너 포털에서 PG 결제를 통해 실제 충전금을 충전합니다. 충전된 금액은 주문 생성 시 자동으로 차감됩니다.

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

잔액 조회

GET /credits API로 현재 충전금 잔액을 조회할 수 있습니다.

bash

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

json

{
  "success": true,
  "message": "Success",
  "data": {
    "paidCreditAmount": 150000,
    "freeCreditAmount": 10000,
    "totalCreditAmount": 160000
  }
}

충전금 차감

주문 생성 시 충전금이 자동으로 차감됩니다. 차감 금액은 주문 금액에 10% VAT가 포함된 금액입니다.

text

차감 금액 = 주문 금액 (ProductAmount + ShippingFee + PackagingFee) + 10% VAT

충전금은 주문 생성(POST /orders) 시점에 즉시 차감됩니다. 잔액이 부족하면 402 Payment Required 에러가 반환됩니다.

충전금 환불

주문 취소 시 충전금이 즉시 환불됩니다. 파트너가 직접 취소할 수 있는 상태는PAID(20)와 PDF_READY(25)입니다.

취소 시점	환불 여부	환불 속도
`PAID` (20)	전액 환불	즉시
`PDF_READY` (25)	전액 환불	즉시

모니터링 권장사항

주문 전 잔액 확인: 주문 생성 전에 GET /credits/balance로 잔액을 확인하세요.
잔액 부족 알림 설정: 잔액이 일정 기준 이하로 떨어지면 알림을 보내도록 설정하세요.
거래 내역 모니터링: GET /credits/transactions로 정기적으로 거래 내역을 확인하세요.

402 에러 처리 패턴

충전금이 부족한 상태에서 주문을 생성하면 402 Payment Required가 반환됩니다. 다음 패턴으로 처리하는 것을 권장합니다.

javascript

async function createOrderWithBalanceCheck(orderData) {
  // 1. 잔액 확인
  const balance = await fetch('/v1/credits/balance', {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }).then(res => res.json());

  if (balance.data.totalCreditAmount < estimatedAmount) {
    // 충전 필요 알림
    throw new Error('충전금이 부족합니다. 파트너 포털에서 충전해주세요.');
  }

  // 2. 주문 생성
  const response = await fetch('/v1/orders', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
    body: JSON.stringify(orderData)
  });

  if (response.status === 402) {
    // 잔액 부족 — 충전 후 재시도
    throw new Error('충전금이 부족합니다. 충전 후 다시 시도해주세요.');
  }

  return response.json();
}