결제 플랫폼과 거래 기록 시스템 통합

새로운 결제 게이트웨이(kp-pay)로 완전히 전환하면서, 거래 기록 관리 체계까지 함께 중앙화하는 대규모 마이그레이션의 P1~P6 골격을 완성했다.

왜 이 시점에 이런 작업이 필요했나

결제 시스템을 바꾼다는 건 단순한 API 변경이 아니다. 결제 게이트웨이(PG) 전환은 사용자의 결제 순간, 환불 처리, 거래 기록, 정산 계산 전체에 물려 있다. 우리가 기존 게이트웨이에서 kp-pay로 옮기기로 결정한 건 몇 가지 이유 때문이다:

• 새로운 결제 수단 지원 — kp-pay는 카카오페이, 네이버페이 같은 현금화 니즈가 높은 수단들을 더 잘 지원
• 정산 자동화 기회 — 현재는 거래 기록이 여러 곳에 산재되어 있고, 정산 과정이 반(半)수동. 이를 중앙화된 "내부원장"으로 통합하면 오류도 줄고 자동화도 가능
• 계약 조건 개선 — 수수료와 정산 주기 모두 유리해짐

그런데 이 정도 규모의 시스템 교체를 한 번에 하면 장애 위험이 크다. 그래서 6단계(P1~P6)로 나누어 진행하기로 팀과 합의했다.

단계별 마이그레이션: P1~P6 로드맵

이번 커밋은 이 P1부터 P6까지의 뼈대를 실제로 코드와 문서로 만든 것이다.

왜 MOCK부터 시작했나

P1에서 "MOCK 환경"을 먼저 구현한 건 의도적인 결정이다.

MOCK은 실제 결제 게이트웨이 서버를 호출하지 않고 그 동작을 흉내 낸다. 예를 들면:

실제 환경:     POST https://api.kp-pay.com/payment/approve → 실제 카드 차감 → 응답
MOCK 환경:     POST http://localhost:내부 포트/mock/payment/approve → 미리 정의된 응답 반환

MOCK을 먼저 만든 이유:

1. 개발 팀 생산성 — 실제 결제 승인 기다릴 필요 없이, 새로운 결제 로직을 즉시 테스트 가능
2. 의도하지 않은 결제 방지 — 개발 중 버그로 인한 "잘못된 결제 승인" 같은 사고 제거
3. 병렬 진행 가능 — 정산팀이 P4(데이터 마이그레이션) 전에 미리 새로운 거래 기록 포맷 검증 가능

이건 외부 서비스 통합 일반의 모범 사례다. MOCK → Staging → Production 순서로 진행하는 게 보안과 품질 관점에서 항상 최선이다.

문서화: 코드만으로는 부족한 이유

이번 작업에서 특별히 신경 쓴 부분은 문서화다. 변경된 파일을 보면:

• .claude/docs/jeju-kp-pay-integration.md — 새로운 kp-pay 통합 가이드 (팀원 온보딩용)
• .claude/docs/jeju-migration-plan.md — 마이그레이션 전체 계획 및 일정
• .claude/docs/api-reference.md — 더 이상 웰컴이 아닌 kp-pay 기반으로 업데이트된 API 스펙

코드 파일들 (partner, pay, settlement 웹 클래스들):
- pay — 결제 승인/취소 로직
- settlement — 거래 기록 저장 및 정산 계산
- partner — 결제 서비스 제공자 정보 관리

결제 시스템처럼 금전이 직결된 도메인에서는 코드만으로 충분하지 않다. "어떤 단계에서 뭘 해야 하는지", "기존과 어떻게 달라졌는지", "이 API를 호출할 때 주의할 점"을 문서로 명확히 해야 팀원들의 실수를 줄일 수 있다. 정산팀, 운영팀과 협업할 때 이런 문서가 없으면 오해가 자주 발생한다.

"내부원장 컷오버"의 실제 의미

"내부원장 컷오버"는 추상적으로 들릴 수 있는데, 실제로는 정산 시스템의 완전한 전환을 의미한다.

Before (현재):
- 웰컴에서 결제 기록을 받음 → 여러 시스템에 산재 → 수동으로 정산 처리

After (목표):
- kp-pay에서 결제 기록을 수신 → 중앙화된 내부원장에 저장 → 자동 정산 계산 및 검증

이렇게 변경되면:
- 정산 오류 감소 (수동 처리 제거)
- 감시와 리포팅 자동화
- 새로운 상품 추가 시 정산 로직이 훨씬 단순해짐

P5에서 실제 내부원장으로 데이터를 "컷오버"할 때가 가장 긴장되는 순간이 될 것이다. 그래서 P1~P4에서 충분히 검증하고, 롤백 계획도 철저히 준비해야 한다.

마주한 과제들

이 커밋은 P1~P6의 골격일 뿐, 이제 실제 전투가 시작된다. P2에서는 실제 kp-pay API와 통합 테스트를 진행해야 하고, P3에서는 저위험 상품부터 점진적으로 롤아웃하면서 모니터링을 강화해야 한다. P4~P5의 데이터 마이그레이션과 내부원장 컷오버 때는 각 단계마다 검증 체크리스트를 만들어서 운영팀과 함께 꼼꼼히 확인해야 할 것 같다.

다음.

🛒 이 글과 어울리는 추천 상품

• 사무의자 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →
• 노이즈캔슬링헤드폰 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.