Skip to main content

결제 시스템 설계 (Payment System Design)

작성일: 2025년 12월 26일 상태: 설계 확정 (Implementation Ready)

이 문서는 Vivid AI 플랫폼의 Vivid Token (VT) 충전을 위한 결제 시스템의 아키텍처와 흐름을 정의합니다.

1. 개요 및 방식 선정​

Vivid AI는 Web3 지갑 연동을 기반으로 하며, 개발 속도와 유지보수성, 그리고 수수료 효율성을 고려하여 "온체인 송금 + 백엔드 검증 (On-chain Transaction + Backend Verification)" 방식을 채택했습니다.

선정 이유​

  • 신속한 구현: 별도의 스마트 컨트랙트(Sale Contract) 개발 및 감사(Audit) 비용 없이, 표준 코인 전송 로직만으로 구현 가능합니다.
  • 수수료 절감: 플랫폼 이용 수수료(Platform Fee)가 없으며, 가스비(Gas Fee) 외의 추가 비용이 발생하지 않습니다.
  • 유연성: 백엔드에서 환율이나 프로모션 로직을 변경하기 용이합니다.

2. 결제 프로세스 흐름 (Workflow)​

3. 데이터 모델 설계​

3.1. PaymentHistory Entity​

결제 내역을 기록하고 중복 처리를 방지하기 위한 엔티티입니다.

필드명타입설명제약조건
idUUID고유 IDPK
userIdUUID결제한 사용자 IDFK (Users)
txHashString블록체인 트랜잭션 해시Unique, Index
amountDecimal실제 지불한 코인 금액Precision: 18, Scale: 8
currencyString지불 통화 심볼 (예: ETH, USDT)
vtAmountInteger충전된 VT 양
statusString상태 (PENDING, SUCCESS, FAILED)
createdAtDate생성 일시

4. 백엔드 구현 명세​

4.1. PaymentsModule​

  • verifyTransaction 메서드:
    • ethers.js 또는 viem 라이브러리를 사용하여 RPC 노드와 통신합니다.
    • Race Condition 방지: 동일한 txHash에 대한 동시 요청을 막기 위해 데이터베이스의 Unique Constraint를 적극 활용하거나 Redis Lock을 고려합니다.

4.2. 환경 변수 (Environment Variables)​

백엔드 .env 파일에 다음 설정이 추가되어야 합니다.

# Payment Configuration
# 결제 대금을 수령할 회사의 지갑 주소
TREASURY_WALLET_ADDRESS=0x1234...abcd 
# 블록체인 네트워크 RPC URL (이미 존재할 수 있음)
BLOCKCHAIN_RPC_URL=https://...

5. 프론트엔드 구현 명세​

5.1. Subscribe Page​

  • 패키지 목록: 하드코딩된 VT 패키지 또는 백엔드에서 불러온 설정값 표시.
  • Wagmi Hooks:
    • useSendTransaction: 실제 코인 전송 트리거.
    • useWaitForTransactionReceipt: 트랜잭션이 블록에 담길 때까지 대기.
  • UX: 트랜잭션 대기 중 로딩 인디케이터 및 성공/실패 토스트 메시지 필수.

6. 보안 고려사항​

  1. Double Spending 방지: txHash 컬럼에 Unique Index를 걸어, 하나의 트랜잭션으로 두 번 충전하는 것을 원천 차단합니다.
  2. 수신자 주소 검증: 트랜잭션의 to 주소가 반드시 TREASURY_WALLET_ADDRESS와 일치하는지 백엔드에서 엄격하게 확인합니다.
  3. 금액 오차 허용 범위: 부동소수점 연산 시 아주 미세한 오차가 발생할 수 있으므로, 검증 시 적절한 허용 오차(Epsilon)를 고려하거나 라이브러리의 BigNumber 기능을 사용합니다.