본문으로 건너뛰기

시나리오 7: 리워드 자동 적용 및 환불 복원

조건​

항목값
설정membership_auto_apply_reward = true
리워드 잔액1 이상
적용 대상첫 구독 (SUBSCRIPTION), 업그레이드 (UPGRADE)

리워드 자동 적용 플로우​

부분 차감 (리워드 < 결제금액)​

전액 차감 (리워드 >= 결제금액)​

환불 시 리워드 복원 플로우​

0원 결제 환불 (PG 결제 없음)​

유료 결제 환불 — 차액 환불 (UPGRADE)​

유료 결제 환불 — 구독 전체 환불 (SUBSCRIPTION)​

상태 변화​

구독 시 리워드 적용​

항목BeforeAfter
포인트 잔액NN - 적용액
결제 금액정가정가 - 적용액
결제 note-autoApplyRewardPoint={적용액}
포인트 트랜잭션-USE / MEMBERSHIP_SUBSCRIBE 또는 MEMBERSHIP_UPGRADE

환불 시 리워드 복원​

항목BeforeAfter
포인트 잔액NN + 복원액
결제 상태PAIDREFUNDED
포인트 트랜잭션-EARN / MEMBERSHIP_REFUND

환불 경로 요약​

결제 유형결제 금액PG 환불리워드 복원 위치
SUBSCRIPTION (유료)> 0원PG API → 웹훅웹훅 (TRANSACTION_CANCELLED)
SUBSCRIPTION (0원)= 0원스킵RefundCommand 직접 처리
UPGRADE (유료)> 0원PG APIRefundCommand 직접 처리
UPGRADE (0원)= 0원스킵RefundCommand 직접 처리

핵심 포인트​

  • 설정 기반: membership_auto_apply_reward 설정이 OFF면 리워드 적용하지 않음
  • 적용 가능 카테고리: 환불 복원(MEMBERSHIP_REFUND) 포함 모든 EARN 카테고리가 차감 대상 (MEMBERSHIP_RENEWAL_ELIGIBLE_EARN_CATEGORIES)
  • 0원 결제: PG 결제 없이 직접 상태 전환, 웹훅도 없음
  • note 기반 복원: autoApplyRewardPoint={amount} 파싱으로 정확한 복원액 결정
  • 멱등성: 클라이언트 전달 키로 환불 후 재결제 시 충돌 방지
  • 복원 만료일: 복원일 기준 +12개월

관련 문서​