로그인한 구매자 본인의 적립금 잔액과 적립·사용 내역을 조회합니다. 스토어프론트(쇼핑몰 화면)의 마이페이지 적립금 화면을 서버에서 그릴 때 씁니다.
- 회원은 회원 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 문서 최초 작성
