---
locale: ko
translated: true
title: "기프트카드 잔액이 증명하는 것과 증명하지 못하는 것"
url: https://insightlog.site/ko/posts/gift-card-api-risk-model
site: "InsightLog"
published: 2026-11-05T09:50:16.986Z
updated: 2026-11-20T09:50:16.986Z
author: "Sofia Almeida"
author_url: https://insightlog.site/ko/authors/sofia-almeida
type: "분석"
category: "기프트카드"
tags: ["기프트카드", "결제", "부정거래 방지", "API"]
reading_minutes: 1
views: 626
upvotes: 26
downvotes: 0
---
## 잔액은 영수증이 아니라 부채입니다

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

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

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

## 네 가지 이벤트를 분리하기

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

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

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

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

## 노출해야 할 것

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

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

## 검토에서 보이는 위험 신호

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

## 마무리

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