여러 체인의 결제 상태를 하나로 관리하는 결제 게이트웨이입니다. 결제 오케스트레이터와 체인별 모니터링 워커, HMAC 서명 웹훅, 운영 화면을 구현했습니다. 중복 요청을 막고 확정이 늦는 거래를 추적해 정산 단계로 넘기도록 구성했습니다.
01 / 담당 범위
체인은 달라도, 결제 상태는 한 곳에서.
결제 상품과 체인 모니터링, 가맹점 알림, Treasury로의 정산 인계를 연결한 게이트웨이입니다. 체인 간 차이만큼 중요한 것은 결제 확정, 웹훅 전달, 후속 정산이 서로 다른 결과라는 점입니다.
Beatoz 공동 dev pilot에서 CPG 영역의 설계·구현·운영 도구를 1인 개발한 사례입니다. 발행사·Treasury·컴플라이언스 서비스를 모두 단독 개발했다는 의미는 아닙니다.
- 담당한 영역
- CPG API, 워커, 운영 화면
- 연동한 경계
- 발행사, Treasury, 인접 pilot 서비스
- 설명의 근거
- 기존 프로젝트 기록 · 원본 코드 감사 아님
02 / 시스템 구성
결제가 어디까지 처리됐는지 구분합니다.
가맹점 / 결제 상품
결제에 필요한 맥락을 만듭니다
가맹점·상점 설정과 통합 결제 세션, 위젯 설정, 커스텀 결제가 API로 시작하는 결제의 진입점입니다.
Strategy / Adapter
네트워크에 맞는 처리를 선택합니다
오케스트레이터가 체인별 어댑터를 선택합니다. QR 데이터와 결제 상태는 결제 화면마다 따로 두지 않고 한 곳에서 관리합니다.
체인별 모니터링 워커
체인에서 발생한 전송을 확인합니다
체인별 워커가 전송을 탐지하고 결제 상태에 반영합니다. 지갑 직접 전송은 조건과 호출 빈도 제한을 둔 스캔으로도 탐지합니다.
별도 진입 경로: 지갑 직접 전송은 API 호출 없이 체인에서 먼저 발생할 수 있습니다.
가맹점 알림과 정산 인계는 하나의 완료 상태가 아닙니다
HMAC 서명 웹훅
가맹점에 결과를 알립니다
전달에 서명을 붙이고 재시도와 기록을 관리합니다. 알림 전달의 성공·실패를 온체인 결제 결과와 혼동하지 않아야 합니다.
정산 큐 → Treasury
정산 작업을 다음 영역으로 넘깁니다
큐 기반 처리와 Treasury 인계 지점으로 업무를 연결합니다. 큐에 넣었거나 인계를 마쳤다는 사실만으로 후속 정산이 완료됐다고 볼 수는 없습니다.
역할을 나눈 세 가지 지점.
공통 결제 처리와 체인별 동작을 분리
- 기록된 구현
- 프로젝트 기록에는 Strategy·Adapter 오케스트레이터와 별도의 체인 워커가 명시돼 있습니다.
- 이 경계가 필요한 이유
- 결제의 맥락과 상태는 공통으로 다루면서 네트워크마다 다른 동작은 어댑터에 나눠 둘 수 있습니다.
- 여기서 확인할 수 없는 것
- 분리만으로 안정성이 보장되지는 않습니다. 어댑터 계약과 검증이 필요하며, 원본 테스트 모음은 이 페이지에 공개돼 있지 않습니다.
결제 상태와 웹훅 전달 상태를 분리
- 기록된 구현
- HMAC 서명, 웹훅 재시도, 전달 기록 저장이 기존 설명에 명시돼 있습니다.
- 이 경계가 필요한 이유
- 알림 전달을 별도로 다루면 가맹점 호출 실패를 결제 자체의 실패로 설명하지 않아도 됩니다.
- 여기서 확인할 수 없는 것
- 재시도 횟수·대기 간격·수신 측 중복 처리 보장까지 이 설명에서 추론할 수는 없습니다.
CPG와 Treasury의 책임 경계를 명시
- 기록된 구현
- 정산 큐와 Treasury 측 처리로 넘기는 인계 지점이 프로젝트 기록에 포함돼 있습니다.
- 이 경계가 필요한 이유
- 결제 처리의 책임과 그다음 재무 업무의 책임을 구분해 설명할 수 있습니다.
- 여기서 확인할 수 없는 것
- 작업을 큐에 넣거나 인계한 것만으로 회계 반영과 외부 정산까지 끝났다고 주장하지 않습니다.
03 / 예외 처리
정상 흐름을 벗어났을 때.
실제 장애나 테스트 통과 기록이 아닌 검토용 예시입니다. 기록된 처리 방식과 이를 확인하는 데 필요한 증거를 구분합니다.
API 세션 없이 전송이 들어왔다면
- 기록된 처리 방식
- API 기반 결제와 별도로 지갑 직접 전송 스캔이 설명돼 있습니다.
- 확인해야 할 질문
- 탐지한 전송이 올바른 결제 맥락에 연결됐다는 근거는 무엇인가?
- 판정에 필요한 자료
- 민감 정보를 제거한 탐지 입력과 연결 판단의 추적 기록.
가맹점 웹훅 호출이 실패했다면
- 기록된 처리 방식
- 서명된 웹훅의 재시도와 전달 기록 저장이 설명돼 있습니다.
- 확인해야 할 질문
- 결제 결과와 알림 결과를 구분하면서 전달을 다시 시도할 수 있는가?
- 판정에 필요한 자료
- 전달 시도 이력과 수신 측에서 재현할 수 있는 테스트.
정산 작업을 인계했다면
- 기록된 처리 방식
- 큐로 분리된 처리와 Treasury 인계가 설명돼 있습니다.
- 확인해야 할 질문
- 인계 확인과 최종 완료를 각각 어떤 근거로 확인하는가?
- 판정에 필요한 자료
- 두 결과가 구분된, 민감 정보를 제거한 영역 간 추적 기록.
구현 범위
기록에 명시된 구현 범위.
Backend API
결제 처리와 정산
- Strategy·Adapter 기반 결제 오케스트레이터
- 체인별 모니터링 워커
- 정산 큐와 처리 API
Dashboards
관리자·가맹점 화면
- 관리자 대시보드
- 가맹점 대시보드
- 결제 운영 도구
Payment Products
위젯·세션·커스텀 결제
- 통합 결제 세션
- 결제 위젯 설정
- 커스텀 결제 흐름
사용 기술
- TypeScript
- NestJS
- PostgreSQL
- Redis
- BullMQ
- Next.js
- TailwindCSS
- Docker
- AWS EC2
- Prometheus
- Grafana
기존 프로젝트 설명 자세히 읽기
풀어야 했던 문제
체인과 결제 방식이 달라도 요청·탐지·확정·정산 상태는 같은 의미를 가져야 했습니다. API로 시작하지 않은 지갑 직접 전송도 찾아 결제 요청과 연결해야 했습니다.
설계와 구현
결제 오케스트레이터와 체인별 어댑터, 모니터링 워커를 분리했습니다. QR 데이터와 결제 상태를 한 곳에서 관리하고 직접 전송을 조건부로 스캔했습니다. 웹훅에는 HMAC 서명과 재시도 기록을 넣고, 관리자와 가맹점 화면에서 처리 상태를 확인하도록 구성했습니다.
개요
- 1인 개발로 진행한 암호화폐 결제 게이트웨이 모노레포입니다.
- API(결제/정산) + 네트워크 모니터링 워커 + 웹훅 + 운영 대시보드로 구성했습니다.
- issuer, treasury, custody, CKYC 등과 함께 운영되는 Beatoz 통합 dev pilot에서 결제 도메인을 담당하도록 구성했습니다.
핵심 구성
0) 스토어(가맹점) 온보딩
- 스토어 페이지 등에서 가맹점 선택을 위한 공개 목록과, Developer Site 전용 상점 등록 플로우를 제공합니다.
1) 결제 오케스트레이션(Strategy/Adapter)
- 체인/결제 타입별 차이를 Strategy/Adapter로 분리해 확장 가능한 결제 엔진을 구성했습니다.
- QR 데이터는 SSOT로 저장하고, 체인 타입에 따라 ‘직접 전송’ 감지/스캔 흐름을 연결했습니다.
1-2) 결제 제품(통합 결제/위젯/커스텀 결제)
- 통합 결제창 생성/설정, 결제 세션 시작 및 상태 조회, 커스텀 결제 플로우 등 “결제 UX 레이어”를 API로 제공합니다.
1-3) 커스터디 월렛(운영 키/서명)
- 커스터디 월렛 생성/요청/관리와 서명 서비스 구성을 포함합니다.
- issuer 연동 및 인접 재무/컴플라이언스 도메인으로 이어질 수 있는 런타임 연결 지점을 함께 고려했습니다.
2) 모니터링 워커(큐 분리)
- 네트워크별 트랜잭션 탐지/컨펌 모니터링을 워커로 분리하고, 큐를 분리해 장애 전파를 줄였습니다.
3) 웹훅 전달(HMAC 서명 + 재시도)
- 외부 시스템 연동을 위해 HMAC 서명 웹훅과 재시도 정책을 구현했습니다.
- 웹훅 전달 결과(성공/실패/재시도)를 기록해 운영 추적이 가능하도록 구성했습니다.
4) 정산/운영 UI
- Admin/Merchant 대시보드로 트랜잭션/정산/상태를 운영 가능하게 제공했습니다.
- 중앙 AWS 기반 dev pilot 배포 레이어에 맞는 런타임 형태로 정리했습니다.
04 / 자료와 한계
이 페이지에서 확인할 수 있는 범위.
- 프로젝트 기록
- 구성 요소와 책임은 기존 포트폴리오 기록을 바탕으로 정리했습니다. 작성자의 작업 설명이며, CPG 원본 저장소를 독립적으로 검증한 결과는 아닙니다.
- 설명용 구조도와 영상
- 위 구조도는 관계를 설명하기 위한 것이고, 첫 화면의 영상은 분위기를 위한 콘셉트 영상입니다. 실제 결제 화면이나 거래 실행 기록으로 제시하지 않습니다.
- 공개된 실행 증거의 한계
- 원본 CPG 저장소, 독립적으로 재현할 수 있는 CPG 테스트 실행 결과, 운영 거래 로그는 이 페이지에서 제공하지 않습니다. 처리량·가용성·전체 흐름의 exactly-once 보장도 수치나 검증 사실로 주장하지 않습니다.
설계 원칙은 관련 글에서 이어집니다.
아래에 연결된 공개 글은 설계 원칙을 설명합니다. 이를 프로젝트의 실행 증거와 구분해서 읽을 수 있습니다.