본문으로 건너뛰기
InsightLogEditorial Notes
메뉴

기프트카드 잔액이 증명하는 것과 증명하지 못하는 것

선불 잔액은 영수증이 아니라 부채 항목입니다. 발급, 사용, 정산이 감사 가능하게 분리된 기프트카드 API를 설계하는 방법을 정리합니다.

Sofia Almeida업데이트 2026년 11월 20일1분 읽기조회 626
X로 공유
긍정 100%

핵심 요약 · TL;DR

잔액은 가치가 충전되었고 아직 사용되지 않았다는 사실만 증명합니다. 소유권이나 현금 수납 여부는 증명하지 못합니다. 신뢰할 수 있는 시스템은 발급, 활성화, 사용, 정산을 각각 독립적이고 멱등한 이벤트로 분리합니다.

Key facts

  • 발급, 활성화, 사용은 각각의 감사 기록을 가진 별도 이벤트여야 합니다.
  • 잔액 조회는 사용 상태를 절대 변경해서는 안 됩니다.
  • 부분 사용과 환불은 잔액 덮어쓰기가 아니라 추가 전용 원장으로 처리합니다.

잔액은 영수증이 아니라 부채입니다

기프트카드는 단순해 보입니다. 충전하고 사용하면 끝입니다. 하지만 운영 환경에서 잔액은 부채 항목이며 결제의 증거가 아닙니다. 두 질문이 자주 뒤섞입니다.

  1. 가치가 발급되었는가?
  2. 현금이 수납되고 정산되었는가?

첫 질문에만 답하는 API는 재무, 분쟁, 부정거래 검토를 지탱할 수 없습니다.

네 가지 이벤트를 분리하기

이벤트답하는 질문잔액 변경
발급카드가 생성되었는가아니오
활성화사용 가능한 상태인가예
사용가치가 소진되었는가예
정산현금이 도착했는가아니오

이 이벤트가 하나의 엔드포인트를 공유하면, 정산 실패가 미활성 카드와 똑같이 보입니다.

멱등성이 곧 보안 통제입니다

모든 사용 요청에는 클라이언트가 만든 멱등 키가 필요합니다. 없으면 네트워크 타임아웃 후 재시도가 카드를 두 번 차감할 수 있습니다. 키를 원장 항목과 함께 저장하고, 같은 키가 반복되면 최초 응답을 그대로 돌려주세요.

노출해야 할 것

  • 통화, 기준 시각, 이벤트 id가 포함된 서명된 잔액 스냅샷
  • 카드와 기간으로 필터링하는 원장 엔드포인트
  • 새 잔액과 원장 항목 id를 함께 반환하는 사용 엔드포인트

내부 카드 번호나 전체 카드 계좌번호를 노출하지 말고, 가맹점 단위로 범위가 제한된 토큰 참조를 사용하세요.

검토에서 보이는 위험 신호

  1. 추가 전용 원장 대신 잔액 덮어쓰기
  2. 같은 키로 두 번 성공하는 사용 엔드포인트
  3. 활성화 배치와 정산 배치의 연결 부재
  4. 타임존이 없는 타임스탬프

마무리

기프트카드를 작은 금융 원장으로 다루세요. 모든 잔액 변경에 이벤트, 멱등 키, 감사 추적이 있으면 API를 신뢰할 수 있습니다.

자주 묻는 질문

기프트카드 잔액은 자금 보증인가요?

아닙니다. 기록된 부채일 뿐입니다. 현금이 실제로 수납되었는지는 별도의 정산 원장이 답합니다.

API가 원시 잔액을 그대로 반환해도 되나요?

통화, 기준 시각, 이벤트 id가 포함된 서명된 스냅샷을 반환해 클라이언트가 오래된 데이터나 재전송을 감지할 수 있게 해야 합니다.

이 글이 도움이 되었나요?

평가는 다른 독자에게 글의 신뢰도를 알려주는 신호가 됩니다.

긍정 100%

Sofia Almeida
Sofia Almeida

Payments and crypto reporter · InsightLog

Reports on gift cards, stablecoin rails, wallets and the fraud controls that keep prepaid money honest.

원문 마크다운: /ko/posts/gift-card-api-risk-model/raw

인용 시 출처: https://insightlog.site/ko/posts/gift-card-api-risk-model

Continue reading

함께 읽으면 좋은 글