Credits API

충전금 잔액·거래 내역 조회와 Sandbox 테스트 API의 엔드포인트 명세를 안내합니다.

충전금 결제 모델·차감/환불 규칙·거래 사유 코드는 충전금 모델을, 운영 절차는 충전금 운영 절차를 참고하세요.

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

충전금 잔액 조회

GET/credits

현재 파트너 계정의 충전금 잔액을 조회합니다.

Request 예시

Request

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

응답 필드

필드	타입	설명
`accountUid`	string	계정 고유 UID
`balance`	number	현재 충전금 잔액 (원)
`currency`	string	통화 코드 (항상 `"KRW"`)
`env`	string	환경 (`"test"` 또는 `"live"`)
`createdAt`	datetime	계정 생성 일시
`updatedAt`	datetime	잔액 마지막 변경 일시

환경 분리: Sandbox/Live 충전금은 분리되어 있으며, API Key의 환경에 해당하는 잔액만 반환됩니다. 충전금 모델 — 환경 분리 참조.

Response 예시

Response (200 OK)

{
  "success": true,
  "message": "성공",
  "data": {
    "accountUid": "u_6b0f********************",
    "balance": 40370.00,
    "currency": "KRW",
    "createdAt": "2026-03-13T12:16:15.000Z",
    "updatedAt": "2026-04-29T02:20:01.000Z",
    "env": "test"
  }
}

HTTP 상태 코드

코드	errorCode	설명
200 OK	—	조회 성공
401 Unauthorized	`ERR_UNAUTHORIZED`	인증 실패
500 Internal Server Error	`ERR_INTERNAL_ERROR`	서버 오류

충전금 거래 내역 조회

GET/credits/transactions

본인 계정의 충전금 거래 내역(충전, 차감, 환불 등)을 조회합니다. 거래는 최근 발생 순(createdAt 내림차순)으로 반환됩니다.

환경 분리: Sandbox/Live 충전금은 분리되어 있으며, API Key의 환경에 해당하는 거래 내역만 반환됩니다. 충전금 모델 — 환경 분리 참조.

Request 예시

Request

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

응답 필드

필드	타입	설명
`transactionId`	number	거래 고유 ID
`accountUid`	string	계정 고유 UID
`reasonCode`	number	거래 사유 코드
`reasonDisplay`	string	거래 사유 설명 (사람이 읽을 수 있는 형식)
`direction`	string	거래 방향 (`+` 증액, `-` 차감)
`currency`	string	통화 (예: `KRW`)
`amount`	number	거래 금액 (원, 부호 포함 — 차감 시 음수)
`balanceAfter`	number	거래 후 잔액 (원)
`memo`	string	거래 메모 (없으면 `null`)
`createdAt`	datetime	거래 일시 (ISO 8601, UTC)
`isTest`	boolean	테스트 환경 거래 여부

응답 각 거래 항목에는 reasonCode(거래 사유 코드)와 reasonDisplay(한글 라벨)가 포함됩니다. 코드별 의미와 발생 시점은 충전금 모델 — 거래 사유 코드를 참고하세요.

Response 예시

Response (200 OK)

{
  "success": true,
  "message": "성공",
  "data": [
    {
      "transactionId": 166,
      "accountUid": "u_6b0f********************",
      "reasonCode": 10,
      "reasonDisplay": "샌드박스 차감",
      "direction": "-",
      "currency": "KRW",
      "amount": -100.00,
      "balanceAfter": 40370.00,
      "memo": "test deduct",
      "createdAt": "2026-04-29T02:20:01.000Z",
      "isTest": true
    },
    {
      "transactionId": 165,
      "accountUid": "u_6b0f********************",
      "reasonCode": 9,
      "reasonDisplay": "샌드박스 충전",
      "direction": "+",
      "currency": "KRW",
      "amount": 1000.00,
      "balanceAfter": 40470.00,
      "memo": "test charge",
      "createdAt": "2026-04-29T02:17:33.000Z",
      "isTest": true
    },
    {
      "transactionId": 163,
      "accountUid": "u_6b0f********************",
      "reasonCode": 3,
      "reasonDisplay": "주문 결제 차감",
      "direction": "-",
      "currency": "KRW",
      "amount": -3520.00,
      "balanceAfter": 39360.00,
      "memo": "주문 결제: or_403T********",
      "createdAt": "2026-04-27T06:15:11.000Z",
      "isTest": true
    }
  ],
  "pagination": {
    "total": 166,
    "limit": 20,
    "offset": 0,
    "hasNext": true
  }
}

HTTP 상태 코드

코드	errorCode	설명
200 OK	—	조회 성공 (거래 없음 시 빈 배열)
401 Unauthorized	`ERR_UNAUTHORIZED`	인증 실패
500 Internal Server Error	`ERR_INTERNAL_ERROR`	서버 오류

Sandbox 충전금 충전 (테스트용)

POST/credits/sandbox/charge

테스트 목적으로 충전금을 충전합니다. 항상 test 충전금에 적용됩니다 (API Key 환경과 무관).

Request Body

필드	타입	필수	설명
`amount`	number	Y	충전할 금액 (원, 양수)
`memo`	string	N	충전 메모 (최대 200자)

memo 인코딩: 한글 memo는 요청 본문이 UTF-8로 정확히 인코딩되도록 Content-Type: application/json; charset=utf-8 헤더를 명시하세요. 인코딩이 맞지 않으면 ModelBinding 단계에서 400 ERR_VALIDATION_FAILED가 반환됩니다.

Request 예시

Request

curl -X POST 'https://api-sandbox.sweetbook.com/v1/credits/sandbox/charge' \
  -H 'Authorization: Bearer {YOUR_API_KEY}' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
  "amount": 1000,
  "memo": "test charge"
}'

응답 필드

필드	타입	설명
`accountUid`	string	계정 고유 UID
`balance`	number	충전 후 잔액 (원)
`currency`	string	통화 코드 (항상 `"KRW"`)
`env`	string	환경 (`"test"` 고정)
`createdAt`	datetime	계정 생성 일시
`updatedAt`	datetime	잔액 갱신 일시

Response 예시

Response (200 OK)

{
  "success": true,
  "message": "샌드박스 크레딧 충전 성공",
  "data": {
    "accountUid": "u_6b0f********************",
    "balance": 40470.00,
    "currency": "KRW",
    "createdAt": "2026-03-13T12:16:15.000Z",
    "updatedAt": "2026-04-29T02:17:33.497Z",
    "env": "test"
  }
}

HTTP 상태 코드

코드	errorCode	설명
200 OK	—	충전 성공
400 Bad Request	`ERR_VALIDATION_FAILED`	`amount` 누락·음수·0, `memo` 인코딩 오류 등
401 Unauthorized	`ERR_UNAUTHORIZED`	인증 실패
500 Internal Server Error	`ERR_INTERNAL_ERROR`	서버 오류

Sandbox 충전금 차감 (테스트용)

POST/credits/sandbox/deduct

테스트 목적으로 충전금을 차감합니다. 잔액 부족 시나리오 등을 테스트할 때 사용합니다.항상 test 충전금에 적용됩니다 (API Key 환경과 무관).

Request Body

필드	타입	필수	설명
`amount`	number	Y	차감할 금액 (원, 양수)
`memo`	string	N	차감 메모 (최대 200자)

Request 예시

Request

curl -X POST 'https://api-sandbox.sweetbook.com/v1/credits/sandbox/deduct' \
  -H 'Authorization: Bearer {YOUR_API_KEY}' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
  "amount": 100,
  "memo": "test deduct"
}'

응답 필드

필드	타입	설명
`accountUid`	string	계정 고유 UID
`balance`	number	차감 후 잔액 (원)
`currency`	string	통화 코드 (항상 `"KRW"`)
`env`	string	환경 (`"test"` 고정)
`createdAt`	datetime	계정 생성 일시
`updatedAt`	datetime	잔액 갱신 일시

Response 예시

Response (200 OK)

{
  "success": true,
  "message": "샌드박스 크레딧 차감 성공",
  "data": {
    "accountUid": "u_6b0f********************",
    "balance": 40370.00,
    "currency": "KRW",
    "createdAt": "2026-03-13T12:16:15.000Z",
    "updatedAt": "2026-04-29T02:20:01.238Z",
    "env": "test"
  }
}

HTTP 상태 코드

코드	errorCode	설명
200 OK	—	차감 성공
400 Bad Request	`ERR_VALIDATION_FAILED`	`amount` 누락·음수·0, `memo` 인코딩 오류 등
401 Unauthorized	`ERR_UNAUTHORIZED`	인증 실패
402 Payment Required	`ERR_INSUFFICIENT_CREDIT`	잔액 부족 — 차감 가능 금액보다 큰 값 요청 시
500 Internal Server Error	`ERR_INTERNAL_ERROR`	서버 오류

Credits API

충전금 잔액 조회

Request 예시

응답 필드

Response 예시

HTTP 상태 코드

충전금 거래 내역 조회

Request 예시

응답 필드

Response 예시

HTTP 상태 코드

Sandbox 충전금 충전 (테스트용)

Request Body

Request 예시

응답 필드

Response 예시

HTTP 상태 코드

Sandbox 충전금 차감 (테스트용)

Request Body

Request 예시

응답 필드

Response 예시

HTTP 상태 코드

관련 문서