# ADR-0004: Async payment handoff via PaymentIntent event
- **Status:** Proposed
- **Date:** 2026-07-10
- **Deciders:** payment-team, order-team, platform-architecture
- **Related:** evaluation finding `perf-order-peak`, C4 Container (Order API, Payment API, Payment PG)
- **Supersedes:** ADR-0005 (on acceptance)
## Context
Architecture evaluation for flash-sale scenario (`perf-order-peak`) showed Order API p99 above 800ms under 10k concurrent checkouts.
Sensitivity analysis:
- Payment API thread pool and PG HTTPS timeout dominate tail latency
- Order API waits on synchronous payment confirmation in the place-order path
ADR-0005 chose synchronous PG calls for simpler reconciliation and faster MVP delivery. Constraints have changed:
- Checkout SLO now requires p99 <= 500ms at peak
- Payment team exposes idempotent `PaymentIntent` API and `PaymentCompleted` event
- Reconciliation job already runs nightly for PG settlement files
## Decision
Move payment authorization off the Order API critical path:
1. Order API publishes `PlaceOrder` and returns `orderId` with status `PAYMENT_PENDING`
2. Payment API consumes intent, calls PG asynchronously, emits `PaymentCompleted` or `PaymentFailed`
3. Order API transitions order state on payment events (idempotent consumer)
4. Client polls or subscribes via WebSocket for final status
Keep PG integration owned by Payment API only (same external boundary as ADR-0005).
## Consequences
### Positive
- Shorter Order API critical path; improved flash-sale latency
- Payment retries and PG outages isolated from order accept path
- Aligns with evaluation action item and load-test plan
### Negative
- UX moves from synchronous to pending state (poll or push required)
- Distributed state: order may exist before payment finality (compensating cancel flow)
- More contract tests across Order and Payment events
### Neutral
- ADR-0001 outbox still applies for `OrderPlaced`; payment events use separate topic
## Alternatives considered
| Option | Why not |
|--------|---------|
| Increase Payment API pool only | Does not remove PG tail from Order path |
| Cache PG responses | Incorrect for authorize; compliance risk |
| Keep sync path for VIP only | Two code paths; operational complexity |
## Follow-up
- Load test with 10k virtual users before Accepted
- On acceptance: mark ADR-0005 Superseded, update C4 dynamic view
- Add AsyncAPI entries for `PaymentIntent` and `PaymentCompleted`
# Architecture Decision Records
Living index for `docs/adr/`. Regenerate or edit when status changes.
| ID | Title | Status | Date | Supersedes / Superseded by |
|----|-------|--------|------|---------------------------|
| 0001 | Use transactional outbox for order events | Accepted | 2026-07-08 | — |
| 0002 | CDC for catalog search projection | Accepted | 2026-07-15 | — |
| 0003 | Modular monolith with hexagonal packages | Superseded | 2025-11-02 | → 0012 |
| 0004 | Async payment handoff via PaymentIntent event | Proposed | 2026-07-10 | replaces 0005 |
| 0005 | Synchronous Payment PG call from Payment API | Superseded | 2025-08-19 | → 0004 |
| 0012 | Split Order as independent deployable service | Accepted | 2026-03-20 | supersedes 0003 |
## Rules
- One decision per file: `NNNN-short-slug.md`
- Never delete; use Superseded / Deprecated / Rejected
- Link both ways on supersede pairs
- Structural PRs that change boundaries require ADR in the same PR (Proposed minimum)
## Review cadence
- Monthly: scan Proposed older than 14 days
- Quarterly: Accepted list vs C4 Container and evaluation findings
# ci excerpt — optional link check
- name: Verify ADR index mentions all files
run: |
for f in docs/adr/[0-9]*.md; do
id=$(basename "$f" | cut -d- -f1)
grep -q "$id" docs/adr/README.md || exit 1
done
소규모팀 — git + README만으로 충분
도구도입전 — PR규칙먼저정착
7. 평가·부채와 연동
이벤트
ADR 행동
평가finding
Proposed ADR 생성
부하테스트통과
Accepted승격
가정깨짐
Supersede 또는 Deprecated
기술부채상환
관련 ADR Follow-up닫기
앞서 evaluation-scenarios.jsonaction 필드 → ADR파일생성
분기평가 — Accepted목록 vs C4diff
8. 안티패턴
안티패턴
대안
사후Confluence정리
PR에 Proposed
인덱스미갱신
merge체크리스트
Supersede없이덮어쓰기
체인유지
아키텍트단독작성
Deciders명시·리뷰
Accepted영원
분기감사
삭제
Rejected·Superseded
9. 실무 체크리스트
질문
좋은 답
언제Proposed?
설계PR시작시
언제Accepted?
합의 + 검증완료
Supersede순서?
신규Accepted → 구Superseded
인덱스누가?
PR작성자
도구?
git우선, 필요 시 adr-tools
주기?
월 Proposed, 분기 Accepted 감사
10. 정리
ADR운영 = PR·리뷰·인덱스·supersede규칙
Proposed → 검증 → Accepted — 평가·테스트와 연결
README표로 현재유효결정한눈
삭제금지, 양방향링크
Part 7 운영 — 다음은 팀 토폴로지
다음에 다룰 것
팀 토폴로지
Conway's Law, stream-aligned·platform 팀, 조직과 아키텍처 정렬
해당 내용은 Fundamentals of Software Architecture (Mark Richards, Neal Ford) 및 Documenting Architecture Decisions (Michael Nygard) 의 내용을 기반으로 합니다.
