적립금 지급·회수·만료 (판매자)

판매자가 특정 회원​(user_id)의 적립금을 수동으로 지급·회수·만료시키는 운영용 API 입니다. 대상 회원을 파라미터로 지정한다는 점이 구매자 본인용 적립금 API(/v1/point/*, 단수형)와 다릅니다.

/v1/point/* (단수) /v1/points/* (복수, 이 문서)
누가 로그인한 구매자 본인 판매자(운영) — 가맹점 서버 전용
대상 회원 회원 본인(회원 JWT 또는 쇼핑몰 서버가 지정한 user_id) user_id 파라미터(대상 회원 — 호출자 세션은 바뀌지 않음)
할 수 있는 일 잔액·내역 조회 지급·회수·만료

인증 방식

secretKey 로 만든 Basic 인증(또는 그 키로 발급한 Bearer 토큰)이 필요합니다. 키체인 키면 supervisor:point_issue·supervisor:point_reclaim·supervisor:point_expire scope 를 받아 둬야 합니다. clientKey(Bootpay-Client-Key 헤더)나 쇼핑몰 도메인만으로는 호출할 수 없습니다.

user_id 는 호출자가 아니라 대상 회원​​입니다. 24자리 회원 ID 면 Bootpay 회원 ID, 그 밖의 값은 이 몰의 외부 회원 ID(ex_uid)로 찾습니다. user_ex_uid·user_external_uid·user_uid 도 같은 뜻이고, 로그인 아이디는 login_id 로 보냅니다. 이 몰의 회원이 아니거나 탈퇴한 회원이면 404 USER_NOT_FOUND 입니다.

HTTP error_code 언제 (세 엔드포인트 공통)
400 TOKEN_AUTHORIZE_TYPE_INVALID Authorization 헤더가 없거나 Basic·Bearer 가 아님
401 API_SCOPE_INVALID 키체인 키에 scope 가 없음
400 REQUIRED_PARAMETER_IS_MISSING user_id(또는 별칭·login_id)가 없음
404 USER_NOT_FOUND 이 몰의 회원이 아니거나 탈퇴한 회원(형식 오류 포함)
403 USER_NOT_MATCH user_id 와 login_id 가 서로 다른 회원

현재 상태 (2026-09-28): 인증·대상 회원 확인을 통과한 요청은 적립금 변경의 감사 기록 단계에서 서버 내부 오류(500 SERVER_ERROR)로 끝납니다. 수정되기 전까지는 연동에 쓰지 마세요. 아래 내용은 코드가 의도한 요청·응답 형식입니다.

POST /v1/points/issue

회원에게 적립금을 지급합니다. 잔액 기록이 없는 회원이면 새로 만든 뒤 지급합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:point_issue
  • 회원 JWT(Bootpay-User-JWT): 필요 없음 (보내도 대상 회원은 user_id 로 정해집니다)

요청

위치 이름 타입 필수 기본값 설명
body user_id string O 대상 회원 — 회원 ID 또는 외부 회원 ID(ex_uid). 별칭 user_ex_uid 등, login_id 도 가능
body amount integer O 지급 금액. 1 이상
body reason string admin_issue 지급 사유 (거래 내역의 reason)

응답

200 OK — 처리 후 잔액

{
  "available_balance": 5500,
  "total_earned": 7000,
  "total_used": 1500,
  "last_purchase_at": "2026-05-24T10:12:00+09:00",
  "expires_at": "2026-11-24T10:12:00+09:00"
}json
필드 타입 설명
available_balance number 사용 가능 잔액 (음수 가능)
total_earned number 누적 적립 금액
total_used number 누적 차감 금액
last_purchase_at string 마지막 구매 시각 (없으면 null)
expires_at string 적립금 전체 만료 예정 시각 (없으면 null)

오류

HTTP error_code 언제
400 POINT_AMOUNT_INVALID amount 가 없거나 0 이하
500 SERVER_ERROR 현재는 검증을 통과한 모든 요청 (위 현재 상태 참고)

인증·대상 회원 오류는 위 인증 방식 표를 봅니다.

응답 형식은 오류를 봅니다.

변경 이력

  • 2026-09-28 인증을 clientKey(쇼핑몰 세션)에서 Basic 인증 + supervisor scope 로 변경, 대상 회원을 이 몰 회원으로 확인(ex_uid·별칭 지원, 없는 회원 404, 누락 400)
  • 2026-09-23 문서 최초 작성

POST /v1/points/reclaim

회원의 적립금을 지정한 금액만큼 회수합니다. 잔액보다 많이 회수하면 잔액이 음수가 될 수 있습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:point_reclaim
  • 회원 JWT(Bootpay-User-JWT): 필요 없음 (보내도 대상 회원은 user_id 로 정해집니다)

요청

위치 이름 타입 필수 기본값 설명
body user_id string O 대상 회원 — issue 와 같음
body amount integer O 회수 금액. 1 이상
body reason string admin_reclaim 회수 사유

응답

200 OK — 처리 후 잔액. 형식은 POST /v1/points/issue 응답과 같습니다.

오류

HTTP error_code 언제
400 POINT_AMOUNT_INVALID amount 가 없거나 0 이하
404 POINT_BALANCE_NOT_FOUND 이 몰에서 적립금 기록이 없는 회원
500 SERVER_ERROR 현재는 검증을 통과한 모든 요청

변경 이력

  • 2026-09-28 인증을 clientKey(쇼핑몰 세션)에서 Basic 인증 + supervisor scope 로 변경, 대상 회원을 이 몰 회원으로 확인(ex_uid·별칭 지원, 없는 회원 404, 누락 400)
  • 2026-09-23 문서 최초 작성

POST /v1/points/expire

회원의 사용 가능 잔액 전부​​를 만료 처리합니다. 금액은 받지 않습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:point_expire
  • 회원 JWT(Bootpay-User-JWT): 필요 없음 (보내도 대상 회원은 user_id 로 정해집니다)

요청

위치 이름 타입 필수 기본값 설명
body user_id string O 대상 회원 — issue 와 같음
body reason string admin_expire 만료 사유

응답

200 OK — 처리 후 잔액. 형식은 POST /v1/points/issue 응답과 같습니다.

오류

HTTP error_code 언제
404 POINT_BALANCE_NOT_FOUND 이 몰에서 적립금 기록이 없는 회원
400 POINT_AMOUNT_INVALID 만료시킬 잔액이 없음 (사용 가능 잔액이 0 이하)
500 SERVER_ERROR 현재는 검증을 통과한 모든 요청

변경 이력

  • 2026-09-28 인증을 clientKey(쇼핑몰 세션)에서 Basic 인증 + supervisor scope 로 변경, 대상 회원을 이 몰 회원으로 확인(ex_uid·별칭 지원, 없는 회원 404, 누락 400)
  • 2026-09-23 문서 최초 작성

함께 보기