적립금

적립금은 구매자에게 주는 돈과 같은 가치입니다. 상점이 정책을 설정해 켠 경우에만 적립합니다. 정책을 설정하지 않은 상점은 모든 적립이 꺼져 있습니다. 구매자는 적립금을 결제에 사용합니다. 적립금이 결제 금액 전체를 덮으면 결제창 없이 바로 주문됩니다.

준비

• 정책·내역 보기: 소유자·관리자·스태프 또는 promotion:r
• 정책 저장, 구매자 적립금 지급·차감: 소유자·관리자 또는 promotion:rw
• 구매자 적립금 조회: customer:r
• 에이전트 토큰의 정책 수정과 지급·차감은 승인을 거칩니다

적립금 설정이 준비 중인 동안에는 정책 저장이 409 POINTS_UNAVAILABLE이고 조회 응답의 available이 false입니다. 적립금 사용이 준비 중인 동안에는 조회 응답의 useAvailable이 false이고, use.enabled를 켜는 저장이 409 POINTS_UNAVAILABLE입니다.

1. 정책

GET·PUT /v1/store/point-policy. 상점 플랫폼은 상점 관리 › 마케팅 › 적립금입니다. PUT은 준 항목만 바꿉니다.

PUT /v1/store/point-policy
{
  "reviewReward": { "enabled": true, "textPoint": 300, "photoPoint": 700 },
  "purchaseEarn": { "enabled": true, "rateBp": 100 },
  "expiryDays": 365
}

바꾼 금액·적립률·유효 기간은 새 적립부터 적용됩니다. 이미 적립된 적립금의 유효 기간은 바뀌지 않습니다.

2. 적립과 회수

• 리뷰: 구매확정한 주문상품에 리뷰를 작성하면 그 시점 정책 금액을 줍니다. 리뷰 작성 응답의 rewardPoint가 그 금액입니다. 리뷰를 삭제하면 받은 금액을 회수합니다. 이미 사용한 적립금이 있으면 다른 적립금에서 빼고, 잔액이 모자라면 0까지만 뺍니다.
• 구매: 구매확정 때 주문상품 실결제 금액(쿠폰 할인과 사용한 적립금을 뺀 금액, 배송비 제외) × 적립률을 줍니다. 1원 미만은 버립니다. 적립률은 결제한 시점의 값입니다. 주문 뒤 정책이나 상품 적립률을 바꿔도 그 주문은 그대로입니다. 비회원 주문과 테스트 결제 주문은 적립하지 않습니다.
• 상품별 적립률: 상품 등록·수정의 pointEarnRateBp입니다. null이면 상점 기본, 0이면 이 상품은 적립하지 않습니다. 구매 적립을 끄면 상품 값과 관계없이 적립하지 않습니다. 상품 적립률을 바꾸는 에이전트 요청은 상품 가격 변경과 같이 승인을 거칩니다.

3. 유효 기간과 소멸

적립한 날로부터 expiryDays일이 지난 날의 끝(한국 시간 23:59:59)에 남은 금액이 소멸합니다. 소멸이 이른 적립금부터 사용합니다. 소멸은 10분마다 처리하고 내역에 EXPIRE로 남습니다.

적립금 원장 이전에 쌓인 잔액은 기존 적립금(OPENING)으로 한 줄 옮겨 둡니다. 기존 적립금의 소멸 시각은 적립금 설정을 연 날 + 상점 유효 기간입니다. 유효 기간을 설정하지 않은 상점은 처음 설정할 때 이 규칙으로 정해지고, 그 전에는 소멸하지 않습니다. 한 번 정해진 소멸 시각은 유효 기간을 바꿔도 그대로입니다.

4. 조회

내역 유형(type): EARN_REVIEW 리뷰 적립 · REVOKE_REVIEW 리뷰 회수 · EARN_PURCHASE 구매 적립 · EXPIRE 소멸 · ADJUST 상점 지급·차감 · OPENING 기존 적립금 · USE_RESERVE 결제 사용 · USE_RELEASE 결제 실패·만료로 되돌림 · REFUND_RESTORE 취소·반품 환불로 반환. 값이 추가될 수 있으니 모르는 값은 그대로 보여 주십시오.

5. 셀러 지급·차감

POST /v1/customers/{customerId}/points/adjustments, 헤더 Idempotency-Key가 필수입니다. 같은 키로 다시 보내면 처음 결과를 돌려줍니다.

{ "amount": 1000, "reason": "이벤트 당첨", "expiresAt": "2027-10-31T23:59:59+09:00" }

• amount가 양수면 지급, 음수면 차감입니다. 사유(reason)는 필수이고 구매자에게는 보이지 않습니다.
• 지급의 소멸 시각은 expiresAt, 생략하면 정책 유효 기간입니다(정책이 없으면 400 POINT_EXPIRY_REQUIRED).
• 차감은 소멸이 이른 적립금부터 뺍니다. 잔액보다 많으면 409 POINT_BALANCE_INSUFFICIENT(details.balance)입니다.
• 조정은 감사 로그(POINT_ADJUSTED)에 남습니다.

6. 결제에 사용

상점이 use.enabled를 켜면 회원이 결제에 적립금을 사용합니다. 비회원은 사용하지 않습니다.

PUT /v1/store/point-policy
{
  "use": {
    "enabled": true,
    "minBalance": 0,
    "minAmount": 1000,
    "unit": 10,
    "maxRatioBp": 10000,
    "includeDeliveryFee": true
  }
}

적용 순서는 즉시할인 → 쿠폰 → 적립금입니다. 사용액은 요청 금액, 잔액, 최대 비율 중 가장 작은 값을 사용 단위로 내린 값입니다. 적립금이 결제 금액 전체를 덮으면 0원 결제입니다(전액 사용은 사용 단위를 보지 않습니다). 남는 결제 금액이 1~99원이면 적립금을 줄여 100원을 남깁니다.

0원 결제

금액 미리보기의 paymentRequired가 false면 결제수단으로 낼 금액이 없습니다. 결제수단 영역을 숨기고 option 없이 결제를 시작하십시오. 판단은 서버가 합니다 — 스토어프론트는 상품·쿠폰·적립금 금액만 넘기고 금액을 계산하지 않습니다. 결제 시작이 그 요청에서 적립금을 쓰고 주문을 만듭니다. 응답은 status: "completed"·orderId이고 payUrl은 null이며, SDK payments.start는 창을 열지 않고 COMPLETED를 돌려줍니다. 주문의 결제수단(payment.method)은 POINT, 결제 금액(totalAmount)은 0입니다. 0원 결제는 재시도할 수 없고 현금영수증이 없습니다. 같은 주문서로 동시에 결제를 시작해도 주문은 하나이고 나머지는 409 ALREADY_PAID입니다. 헤더 Idempotency-Key를 보내면 같은 키의 재요청에 처음 결과를 돌려줍니다.

스토어프론트 흐름은 쿠폰과 같습니다.

1. 주문서 응답의 points에 잔액(balance)·최대 사용액(maxUsable)·사용 단위가 옵니다. 비회원이거나 상점이 사용을 끄면 null입니다.
2. 금액 미리보기 POST /checkout/{checkoutId}/pricing에 pointAmount를 보내면 실제 사용액(amounts.pointAmount)과 주문상품별 배분(items[].pointAllocation)이 옵니다. 100원을 남기려고 줄였으면 points.adjustReason이 MIN_PAYMENT이고, 사용하지 못하면 points.rejectReason(MIN_BALANCE·MIN_AMOUNT·NOT_PAYABLE)이 옵니다. 미리보기는 적립금을 잡아 두지 않습니다.
3. 결제 시작 POST /checkout/{checkoutId}/payment에 같은 pointAmount를 보냅니다. 결제 시작이 그 금액을 잔액에서 빼 둡니다(내역 USE_RESERVE). 계산한 뒤 잔액이 줄었으면 409 POINT_BALANCE_CHANGED이니 미리보기부터 다시 하십시오. 결제가 실패하거나 결제 시간이 지나면 빼 둔 적립금을 돌려줍니다(USE_RELEASE).

주문 응답은 결제에 사용한 적립금을 payment.pointAmount, 주문상품별 몫을 items[].pointAllocation으로 싣습니다. 현금 결제 금액은 payment.totalAmount입니다. 상품 줄에 먼저 나누고, 남는 몫은 배송비에 씁니다.

7. 취소·반품 환불

적립금으로 낸 몫은 적립금으로, 현금으로 낸 몫은 현금으로 돌려줍니다.

• 취소·반품 수량의 현금 몫은 totalPrice − couponDiscountAmount − pointAllocation의 수량 비율이고, 적립금 몫은 pointAllocation의 수량 비율입니다. 나눠 취소해도 합이 결제 금액과 같습니다.
• 반품 배송비·추가 차감 같은 차감은 현금에서 먼저 빼고, 모자란 몫만 적립금에서 뺍니다. 그래도 모자라면 0에서 멈춥니다.
• 응답과 웹훅의 refundAmount는 현금 환불, pointRefundAmount는 돌려준 적립금입니다. 구매자 클레임 접수 응답·클레임 조회에는 예상액(pointRefundAmount·expectedPointRefundAmount)이 옵니다.
• 돌려준 적립금은 내역에 REFUND_RESTORE로 남습니다. 소멸 시각은 그 결제에 사용한 적립금 중 가장 늦은 소멸 시각이고, 이미 지났으면 돌려준 날로부터 30일 뒤의 끝입니다.
• 탈퇴한 구매자에게는 적립금을 돌려주지 않습니다. 현금 환불은 그대로 합니다.
• 0원 결제 주문은 현금 환불이 없어 PG를 부르지 않고 적립금만 돌려줍니다(부분 취소 포함).

8. 스토어프론트 화면

금액은 모두 서버가 계산한 값입니다. 화면은 응답 값을 그대로 보여 주고 적립액·사용액을 직접 계산하지 않습니다.

purchasePoint는 회원 주문을 구매확정할 때 받는 예정액입니다. 실제 적립은 결제한 금액(쿠폰 할인과 사용한 적립금을 뺀 금액)으로 다시 계산하므로 안내 금액과 다를 수 있습니다.

MCP 템플릿에는 상품 상세 적립 안내, 후기 블록의 리뷰 혜택 안내, 내 적립금 화면(/points)이 들어 있습니다.