적립금 (구매자 본인)

로그인한 구매자 본인​​의 적립금 잔액과 적립·사용 내역을 조회합니다. 스토어프론트(쇼핑몰 화면)의 마이페이지 적립금 화면을 서버에서 그릴 때 씁니다.

  • 회원은 회원 JWT(Bootpay-User-JWT) 또는 user_id 중 하나로 정합니다.
    • user_id 는 쇼핑몰 서버가 자기 로그인 세션의 회원 ID 를 쿼리로 넣어 보냅니다. 24자리 회원 ID 면 Bootpay 회원 ID, 그 밖의 값은 이 몰의 외부 회원 ID(ex_uid)로 찾습니다. user_ex_uid·user_external_uid·user_uid 도 같은 뜻입니다.
    • user_id 는 secretKey 인증(Basic·Bearer)일 때만 받습니다. 브라우저가 보낸 값을 그대로 넘기지 마세요 — 인증 — 호출 구조.
    • 둘 다 보내면 JWT 가 우선이고, 서로 다른 회원이면 403 USER_NOT_MATCH 입니다.
  • 조회 전용입니다. 적립금을 지급·회수·만료시키는 판매자용 API(/v1/points/*, 복수형)는 정비 중이라 공개 문서에서 제외했습니다.

적립금 금액은 원 단위 정수입니다.

GET /v1/point/balance

현재 적립금 잔액과 누적 적립·사용 금액을 돌려줍니다. 적립금 기록이 한 번도 없는 회원도 오류 없이 0 으로 응답합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:point_balance
  • 회원: JWT 또는 user_id 필수 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정) — 회원 JWT

요청

파라미터가 없습니다.

응답

200 OK

{
  "available_balance": 3500,
  "total_earned": 5000,
  "total_used": 1500,
  "is_negative": false
}json
필드 타입 설명
available_balance number 지금 쓸 수 있는 잔액. 후기 삭제에 따른 회수 등으로 음수​​가 될 수 있습니다
total_earned number 누적 적립 금액
total_used number 누적 차감 금액(사용·회수·만료 포함)
is_negative boolean 잔액이 0 보다 작으면 true. 음수 잔액은 다음 적립 때 먼저 상쇄됩니다

오류

HTTP error_code 언제
401 USER_SESSION_INVALID JWT·user_id 가 모두 없거나 JWT 세션이 끝남
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원
400 API_PARAM_INVALID clientKey 만으로 인증한 요청에 user_id 를 보냄 (payload.reason: merchant_auth_required)

그 밖의 회원 JWT 오류(USER_JWT_INVALID)는 회원 JWT, 인증·scope 오류는 오류를 봅니다.

변경 이력

  • 2026-09-28 회원을 JWT 또는 user_id(쇼핑몰 서버 지정)로 정할 수 있게 변경
  • 2026-09-23 문서 최초 작성

GET /v1/point/transactions

적립금 거래 내역을 최신순으로 돌려줍니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:point_transactions
  • 회원: JWT 또는 user_id 필수 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정) — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
query page integer 1 페이지 번호 (1 부터)
query limit integer 20 페이지 크기
query transaction_type integer 거래 유형으로 거르기. 값은 아래 type 표

이 API 는 페이지네이션 공통 규칙(잘못된 값 보정, 최대 100)을 적용하지 않습니다. page·limit 은 1 이상의 정수로 보내세요. page 나 limit 에 0 이하를 보내면 500 SERVER_ERROR 가 납니다.

응답

200 OK

{
  "transactions": [
    {
      "_id": "6650f0c2a1b2c3d4e5f60789",
      "type": 1,
      "status": 2,
      "amount": 500.0,
      "balance_snapshot": 3500.0,
      "source": 1,
      "reason": "구매 적립",
      "order_id": "6650e1a0a1b2c3d4e5f60001",
      "order_number": "2405240001",
      "order_name": "유기농 원두 1kg",
      "product_review_id": null,
      "earned_at": "2026-05-24T10:12:00+09:00",
      "available_at": "2026-05-24T10:12:00+09:00",
      "remaining_balance": 500.0,
      "created_at": "2026-05-24T10:12:00+09:00"
    }
  ],
  "total_count": 12,
  "page": 1,
  "limit": 20,
  "total_pages": 1
}json

목록 키가 공통 형식(list·count)이 아니라 transactions·total_count 입니다.

필드 타입 설명
transactions[] array 거래 내역
transactions[]._id string 거래 ID (이 필드만 _id 로 옵니다)
transactions[].type integer 거래 유형. 1 적립 · 2 사용 · 3 회수 · 4 상쇄 · 5 만료 · 6 복구 · 7 관리자 조정
transactions[].status integer 1 지급 대기 · 2 사용 가능 · 3 사용 완료 · 4 만료 · 5 회수
transactions[].amount number 금액. 적립은 양수, 차감은 음수
transactions[].balance_snapshot number 이 거래 직후의 잔액
transactions[].source integer 발생 원인. 1 주문 · 2 상품 후기 · 3 시스템
transactions[].reason string 사유
transactions[].order_id string 관련 주문 ID (없으면 null)
transactions[].order_number string 관련 주문번호 — 주문 상세 링크용 (없으면 null)
transactions[].order_name string 관련 주문명 (없으면 null)
transactions[].product_review_id string 관련 상품 후기 ID (없으면 null)
transactions[].earned_at string 적립(발생) 시각, ISO 8601
transactions[].available_at string 사용 가능해진 시각, ISO 8601
transactions[].remaining_balance number 이 적립분 중 남은 금액
transactions[].created_at string 기록 시각, ISO 8601
total_count integer 조건에 맞는 전체 건수
page integer 요청한 페이지
limit integer 요청한 페이지 크기
total_pages integer 전체 페이지 수

오류

HTTP error_code 언제
500 SERVER_ERROR page 또는 limit 이 0 이하
401 USER_SESSION_INVALID JWT·user_id 가 모두 없거나 JWT 세션이 끝남
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원
400 API_PARAM_INVALID clientKey 만으로 인증한 요청에 user_id 를 보냄 (payload.reason: merchant_auth_required)

그 밖의 회원 JWT 오류는 회원 JWT, 인증·scope 오류는 오류를 봅니다.

변경 이력

  • 2026-09-28 회원을 JWT 또는 user_id(쇼핑몰 서버 지정)로 정할 수 있게 변경
  • 2026-09-23 문서 최초 작성

함께 보기