Voucher — 금액형 상품권/기프트카드
증서형 가치수단 — 코드가 있는 발행물을 배치로 발행·유통하고, 회원이 등록(redeem)하면 지갑 크레딧으로 적립됩니다. (ADR-107, v0.1.0)
발행(issued) → 전달(delivered) → 사용(redeemed)
↘ 만료(expired) / 폐기(void)
운영자 가이드
활성화 — 항상 노출, 사이트별 사용 토글 (ADR-096)
상품권 기능은 기본으로 항상 탑재됩니다. 설정 탭(사이트 설정 › 지갑·상품 권)은 항상 보이며, 사이트별 사용 on/off 는 플러그인 관리 화면에서 토글합니다(기본은 켜짐). 끄면 관리 메뉴·회원 redeem 화면이 자동 숨김.
php artisan migrate # voucher_batches / vouchers
Wallet plugin 이 사이트에서 켜져 있어야 redeem 이 동작합니다 (지갑 미사용 시 안내 후 거부). 개발자 참고: 프로젝트 화면 게이팅은
isEnabledForCurrentScope('voucher')참조.
배치 발행
상품권 발행 > 배치 발행 액션 (재인증 step-up):
| 필드 | 설명 |
|---|---|
| 액면가 / 수량 | 코드 1개당 적립 금액 · 발행 매수 (최대 10,000) |
| 적립 유형 | 보너스 크레딧(기본 — 무상 증정·이벤트) / 충전 크레딧(유상 판매분 — 환불 대상 선수금) |
| PIN 사용 | 6자리 PIN 동봉 (redeem 시 요구) |
| 만료일 | 경과 시 redeem 불가 |
⚠️ 돈 받고 파는 상품권은 반드시 "충전 크레딧" 유형으로 발행하세요 — 회계상 선수금이며 환불 정책 대상입니다.
코드 관리
- 목록은 마스킹(앞 4자) — 「코드 열람」 시 원문+PIN 표시 & 감사 로그 기록
- 전달 표시(선물/발송 추적) · 무효화(폐기)
- 현황 위젯(배치 목록 상단): 발행 수 · 사용(redeem) 수 · 사용률 · 미상환 액면(미사용 유효 상품권 합계)
정책 설정 (관리페이지 · 권장)
사이트 설정 › 지갑·상품권 › 상품권 탭에서 사이트 단위로 설정합니다:
| 항목 | 설명 |
|---|---|
| 상품권 등록 페이지 | 회원 redeem 페이지 노출 on/off |
| 발행 재인증 | 배치 발행 시 step-up 요구 + 유효시간(60~3600초) |
우선순위 Tenant > SaaS > .env > 코드 기본, 미설정 = 기존 동작(하위호환). step-up 정책 변경 저장에는 재인증이 요구됩니다.
회원 사용
내 지갑 → 🎁 상품권 등록 또는 /user/vouchers/redeem — 코드(+PIN) 입력 → 지갑 적립.
동일 코드 재등록은 무해(중복 적립 없음), 타인이 쓴 코드는 거부됩니다.
개발자 가이드
use App\Core\Base\Voucher\Contracts\VoucherRedeemerInterface;
app(VoucherRedeemerInterface::class)->redeemByCode($user, $code, $pin);
// 이벤트: VoucherRedeemed(voucher, userId, faceValue, creditedAccountType)
- 상품권을 Commerce 상품으로 판매: 예시
plugins/Voucher/docs/examples/VoucherSaleFulfiller.php - 후속 예정: 상품 교환권(특정 상품형) · Wallet 없는 직접차감 모드