선결제 상세 운영 규칙 통합
ADR-160 선결제 상세 운영 규칙 통합
1. Metadata
- ADR ID: ADR-160
- Status: draft
- Date: 2026-03-09
- Owner: YSY
2. Domain Decision
- PG 리다이렉트 결과 확인 절차를 표준화한다.
- 선결제 픽업 시 검증/인도 책임 경계를 명확히 한다.
- 정산/분쟁 이벤트 흐름을 상태 기준으로 관리한다.
prepaid 결제 성공 시 예약 상태는 우선 reserved로 확정한다.redeemed 전이는 verification_method(none|location|qr) 조건에 따라 결정한다.- 선결제 기능은 PG 연결이 완료된 파트너에게만 활성화한다.
- 파트너 PG 기본 메타데이터(
pg_type, pg_mid, pg_redirect_url)가 없으면 선결제 발행을 허용하지 않는다.
3. Product Decision
- 선결제 적용 대상 업종/상황 기준을 정의한다.
- 선결제 완료 시 상태 전이 정책을 고정한다.
- 픽업 미이행 분쟁 책임 경계를 명확히 한다.
- 선결제 분쟁은 발행자-사용자 직접 해결 원칙으로 안내한다.
- 선결제 업종 기준은 ADR-005
업종 코드 체계 거버넌스의 canonical 코드 체계를 사용한다.
4. UX Decision
- 선결제 완료 후 픽업 안내 흐름을 표준화한다.
- 픽업 시 검증 방식에 따른 안내를 분기한다.
- 분쟁 발생 시 즉시 확인 가능한 정보만 노출한다.
5. Tech Decision
- PG 리다이렉트 결과 검증 절차를 표준화한다.
- 결제 확인 지연/중복 콜백을 멱등 처리한다.
- PG 장애 시 안전한 실패 전이를 보장한다.
- 결제 성공 콜백은 예약 상태를
reserved로 확정하고 verification_method 규칙에 따라 redeemed 전이를 처리한다. - 발행자 PG 메타데이터는
pg_type, pg_mid, pg_redirect_url을 최소 필수로 저장한다. - PG 시크릿은 원문 저장을 금지하고
pg_api_key_ref, pg_secret_key_ref, pg_webhook_secret_ref 참조키로만 저장한다. - 로그/운영 화면에서 PG 시크릿 원문은 마스킹 없이 노출하지 않는다.
- 결제 결과 처리에 필요한 기본 라우팅 키는
order_id, reservation_id를 필수로 사용한다. - 선결제 가능 업종 판정은 매장
category canonical 값(ADR-005 기준)으로 수행한다.
6. Ops Decision
- PG 장애 시 우회/중단/복구 절차를 정의한다.
- 정산 불일치 탐지/수정 절차를 운영한다.
- 장애 공지 템플릿과 후속 리포트를 표준화한다.
- 선결제 분쟁은 직접 해결 원칙과 증적 안내 절차로 처리한다.
7. Implementation Contract (Optional)
7.1 API Contract
- 결제 콜백 입력은
order_id, reservation_id, 서명 검증값을 필수로 받는다. - 중복 콜백은 멱등 처리하고 최초 확정 결과를 재반환한다.
7.2 Data Contract
- PG 시크릿은 참조키(
pg_api_key_ref, pg_secret_key_ref, pg_webhook_secret_ref)만 저장한다. - 선결제 사용 가능 조건은 파트너 PG 메타데이터(
pg_type, pg_mid, pg_redirect_url) 존재로 판정한다.
7.3 Error/Observability Contract
- 서명 불일치는
PG_CALLBACK_INVALID_SIGNATURE로 기록한다. - 정산 불일치/콜백 지연을 별도 운영 알람으로 분리한다.
7.4 Test/Acceptance Contract
- 성공 콜백 수신 시 상태가
reserved로 확정되어야 한다. verification_method=none이면 즉시 reserved -> redeemed, qr|location이면 검증 성공 시 redeemed로 전이해야 한다.- 동일 콜백 재전송 시 상태/정산 결과가 변하지 않아야 한다.
8. Validation
Buy me a coffee