Digital Payment 전체 흐름 구현

앞선 튜토리얼을 하나의 구현 순서로 정리합니다.

1. 연동 초기화

Base URL, API Key, HMAC Key를 Secret Manager에 저장합니다.
/health와 /time을 확인하고 호출 서버 시각을 동기화합니다.
기준정보 API에서 USDT와 Sepolia ID를 조회합니다.
해당 자산·네트워크 조합이 활성 상태인지 검증합니다.

2. 결제 계정 준비

고객 모델에 맞춰 USER 계정을 생성하거나 재사용합니다.
가맹점 결제 역할의 BUSINESS 계정을 생성하거나 재사용합니다.
두 계정 ID를 별도로 저장하고 유형과 상태를 검증합니다.

3. 고객 자금 충전

선택한 자산과 네트워크의 입금 주소를 발급합니다.
EXTERNAL 입금 cursor로 고객 입금을 탐지합니다.
발견한 모든 비최종 입금은 ID로 추적하고 status: COMPLETED일 때만 충전 완료로 처리합니다.
고객의 사용 가능 raw 잔액이 결제 금액 이상인지 확인합니다.

4. 결제 처리

text

고객 USER 계정
  → 고유 client_request_id로 POST /withdrawals/internal
  → 가맹점 BUSINESS 계정

요청 전에 주문 ID와 client_request_id를 저장하고, 응답을 받은 뒤 withdrawal_id를 연결합니다.
타임아웃이 발생하면 같은 client_request_id로 결과를 복구합니다.
내부 거래가 COMPLETED일 때만 주문을 결제 완료로 처리합니다.
잔액 변화는 보조 정합성 검사에만 사용합니다.

5. 가맹점 자금 정산

선택한 자산 기준으로 외부 주소를 검증합니다.
견적을 요청하고 transfer_type: EXTERNAL인지 확인합니다.
전역에서 고유한 새 client_request_id로 외부 출금을 생성합니다.
중간 처리 상태에서는 정산 대기를 유지합니다.
양쪽 상태가 COMPLETED이고 tx_hash가 유효할 때만 완료 처리합니다.

6. 지속적인 거래 대사

고객 입금과 고객이 보낸 결제를 별도 cursor로 읽습니다.
가맹점 수취 내역은 INTERNAL_IN 원장에서 읽습니다.
가맹점 외부 정산은 출금 목록과 WITHDRAW 원장에서 읽습니다.
최종 상태가 아닌 업무 레코드는 ID로 조회하고, append-only 원장은 cursor로 동기화합니다.

운영 적용 규칙

IMPORTANT

PoC가 단순한 처리만으로 성공하더라도 운영 환경에서는 다음 규칙을 적용하십시오.

내부·외부 출금 전체에서 client_request_id를 재사용하지 않습니다.
HTTP 응답이 유실되었다는 이유만으로 생성 요청을 다시 보내지 않습니다.
지역화될 수 있는 오류 message로 분기하지 않고 HTTP 상태, error.code, error.action을 사용합니다.
자산 금액은 정수 또는 decimal-safe 연산을 사용합니다.
재시도는 제한 횟수와 지수 백오프를 적용하고 오류 action이 허용할 때만 수행합니다.
API Key와 HMAC Key를 클라이언트 앱, 소스 저장소, 로그, 지원 문의에 노출하지 않습니다.

전체 요청·응답 스키마는 Wallet API Reference에서 확인할 수 있습니다.