모든 money movement는 통화별 차변·대변 합계가 같은 immutable entries를 만듭니다.
디지털 월렛
시스템 설계
잔액 숫자는 빠른 읽기 화면일 뿐, 돈의 진실은 변경되지 않는 분개에 있습니다. 사용 가능·보류 잔액, 멱등 송금, 위험 심사, 외부 결과와 조정을 하나의 복구 가능한 상태 기계로 설계합니다.
원장·잔액송금 상태위험·조정면접 답변진도 저장
30초 핵심 요약
잔액 테이블이 아니라 immutable double-entry ledger를 정본으로 둡니다. 전송은 source available에서 reserved로 먼저 옮기고, 허용된 결과만 post 또는 release합니다. 외부 rail timeout·webhook·risk review는 새 금전 효과를 만들지 않고 같은 transfer와 provider reference를 보강합니다.
InvariantΣ debit = Σ credit
Spendableavailable ≠ total history
Recoveryreverse, never overwrite
01 · REQUIREMENTS
# 요구사항현재 잔액, 미래 결과, 감사 기록의 책임을 분리한다
월렛은 보여 주는 잔액보다 먼저 무엇을 이미 확정했는지, 무엇을 심사·정산 때문에 보류했는지, 무엇을 되돌릴 수 있는지 말할 수 있어야 합니다.
심사·외부 정산 중인 자금은 available과 분리해 이중 지출을 막습니다.
idempotency key, workflow state, inbox/outbox가 재시도와 비동기 중복을 묶습니다.
오류는 update가 아닌 reversal과 provider/은행 대사 근거로 해결합니다.
02 · HIGH-LEVEL DESIGN
# 아키텍처정책 결정, 원장 commit, 외부 결과를 분리한다
risk/AML/제재 screening은 allow·review·block workflow의 입력입니다. 원장은 정책 결과와 provider outcome을 증명 가능한 state transition으로 기록하며, projection은 빠른 잔액 읽기를 위한 파생 데이터입니다.
digital wallet transfer: authorize → reserve → post/release → reconcile SVG DIAGRAM · ledger is source of truth
원장 경계: `available → reserved`와 `reserved → destination/clearing`은 상태가 다른 균형 분개입니다. risk review나 PSP timeout 동안 destination balance에 먼저 credit하지 않으며, projection의 숫자보다 ledger transaction의 invariant가 우선합니다.
03 · REQUEST FLOW
# 요청 흐름예약된 자금은 post 또는 release 중 하나로만 끝난다
ownership·integer amount·currency·limit·idempotency fingerprint를 확인합니다.
policy/risk가 block, review, allow 중 하나를 선택하고 decision version을 기록합니다.
source available을 줄이고 reserved를 늘리는 ledger transaction과 outbox를 함께 commit합니다.
verified outcome만 수취/clearing으로 post하고 실패·만료는 release 또는 reversal합니다.
04 · TRADEOFFS
# 대안 비교빠른 balance read와 검증 가능한 value movement를 섞지 않는다
선택
강점
제약
설계 판단
mutable balance만
단순 read
감사·재생·정정 취약
금전 시스템의 유일 정본으로 쓰지 않음
immutable ledger + projection
균형·복구
schema·replay 운영
실제 value movement 기본
즉시 posted
짧은 UX
review/external outcome 불명
저위험 내부 전송만 제한
reserve → post/release
이중 지출 차단
expiry·case 운영
외부 rail·고위험 전송
05 · FAILURE MODES
# 장애 9가지중복·지연·불일치를 숫자가 아닌 상태와 근거로 복구한다
중복 POST
재시도 또는 두 화면이 같은 송금을 두 번 만들 수 있습니다.
대응 · idempotency key·fingerprint로 첫 transfer와 response만 재사용합니다.
projection lag
잔액 화면이 ledger commit보다 늦어 고객이 낡은 수치를 봅니다.
대응 · ledger position/as-of 표시, replay와 read-your-writes 경로를 둡니다.
outbox worker crash
reserve는 커밋됐지만 provider request가 아직 실행되지 않습니다.
대응 · transactional outbox replay와 stuck reserve age alarm으로 처리합니다.
provider timeout
외부 송금이 됐는지 실패했는지 즉시 알 수 없습니다.
대응 · 새 호출 대신 provider reference 조회·signed webhook으로 unknown을 해소합니다.
webhook 재전송·역순
늦은 event가 posted/reversal을 중복 적용하려 합니다.
대응 · inbox dedupe, signature, 단조 transition으로 차단합니다.
risk review 지연
자금이 reserve에 너무 오래 묶여 사용 가능 잔액이 줄어듭니다.
대응 · review SLA, safe expiry release, case escalation을 둡니다.
부분 분개
한쪽 entry만 보이면 잔액·재무 보고가 깨집니다.
대응 · atomic DB transaction, `debit=credit` monitor, append-only repair를 사용합니다.
reconciliation 차이
은행/PSP 명세와 내부 ledger totals가 다를 수 있습니다.
대응 · case 격리, 근거 기반 reversal/adjustment, ageing SLO를 둡니다.
account takeover
탈취자가 수취인·출금을 바꾸고 자금을 이동하려 합니다.
대응 · step-up auth, velocity limit, device anomaly, hold와 human case를 결합합니다.
06 · OPERATIONS
# 운영 관점보안·관측·비용은 원장의 주변 기능이 아니라 일부다
PII·credential·risk signal·ledger는 접근·보존 경계를 분리합니다. provider tokenization, secret rotation, step-up auth와 redacted telemetry를 기본으로 둡니다.
least privilege · redaction · audit
debit/credit invariant, reserve age, transfer state, outbox/inbox lag, projection position, webhook reject, provider discrepancy를 따로 관측합니다.
Σ debit = Σ credit
immutable history·backup, balance read model, provider·webhook·settlement, risk/screening vendor와 human review, KMS·audit 비용을 합산합니다.
ledger + projection + risk + ops
면접 모드 · 추가 질문07:00
“외부 출금 요청이 timeout이 됐고, risk review는 아직 끝나지 않았으며 사용자는 다시 송금을 누릅니다. 금액 integer/통화, available/reserved account, idempotency, provider reference, webhook, 원장 reversal과 reconciliation을 어떤 순서로 설명하시겠습니까?”
immutable double entryreserve → post/releaseunknown ≠ failedrisk boundaryreconcile evidence
SOURCES
공식·1차 출처와 설계 가정
- Stripe API — Idempotent requests: POST 재시도와 idempotency key 경계.
- Stripe Docs — Webhooks: signature 검증과 비동기 event 처리.
- PCI Security Standards Council — PCI DSS: 결제 계정 데이터 보호 자료.
- FinCEN — Bank Secrecy Act / AML: 미국 BSA/AML 관련 공식 자료의 진입점.
- U.S. Treasury OFAC — Sanctions Programs: 제재 프로그램·국가 정보.
- PostgreSQL — Transaction Isolation: concurrent transaction과 재시도 경계.
- 이 페이지의 QPS·risk 비율·보류 정책·상태 전이·비용은 학습용 설계 가정/제안이며, 실제 적용 전 관할 법률·라이선스·partner 계약과 보안 검토가 필요합니다.
LEARNING ROADMAP다음 시스템 디자인 주제 보기
EDITORIAL NOTES
작성·검토·참고 자료
참고 자료
- Stripe API — Idempotent requests — POST 재시도와 idempotency key 동작을 확인했다.
- Stripe Docs — Webhooks — webhook 서명 검증과 비동기 event 처리 경계를 확인했다.
- PCI Security Standards Council — PCI DSS Document Library — 결제 계정 데이터 보호 기준의 공식 자료를 확인했다.
- FinCEN — Bank Secrecy Act / AML — 미국 BSA/AML 관련 법령·규정 자료의 공식 진입점을 확인했다.
- U.S. Treasury OFAC — Sanctions Programs and Country Information — 제재 프로그램·국가 정보의 공식 자료를 확인했다.
- PostgreSQL — Transaction Isolation — concurrent transaction·재시도 경계 검토에 사용했다. 이 문서의 QPS, 보류 TTL, risk 처리율, 상태 전이, shard/partition, 비용 모델은 공개 성능 수치가 아닌 학습용 **설계 가정/제안**이다.
사실 오류·출처 정정은 문의·정정 페이지로 알려 주세요.