결제 상태 조회

결제의 현재 상태를 조회합니다.

• 인증: x-public-key 헤더 필수
• GET 요청 시 Origin 헤더 대신 x-origin 헤더 사용 가능 (프록시 환경)

REST API

curl https://gateway.dev.solonetwork.io/api/v1/payments/0xabc123... \
  -H "x-public-key: pk_xxxxx"

응답

성공 (200 OK)

{
  "success": true,
  "data": {
    "paymentId": "0xabc123...",
    "orderId": "order-001",
    "status": "PAID",
    "chainId": 80002,
    "tokenAddress": "0xE4C687167705Abf55d709395f92e254bdF5825a2",
    "tokenSymbol": "SUT",
    "tokenDecimals": 18,
    "tokenPermitSupported": true,
    "gatewayAddress": "0x...",
    "forwarderAddress": "0x...",
    "amount": "10500000000000000000",
    "recipientAddress": "0xMerchantWallet...",
    "merchantId": "0x...",
    "deadline": "1706281200",
    "successUrl": "https://example.com/success",
    "failUrl": "https://example.com/fail",
    "expiresAt": "2024-01-26T12:35:00.000Z",
    "txHash": "0xdef789...",
    "payerAddress": "0x...",
    "createdAt": "2024-01-26T12:30:00Z",
    "currency": "USD",
    "fiatAmount": 10.5,
    "tokenPrice": 1.0
  }
}

• txHash -- 결제 트랜잭션 해시. 사용자가 결제를 완료하여 PAID 이후 상태일 때 존재합니다.

주요 응답 필드

필드	타입	설명
paymentId	string	결제 고유 ID
orderId	string	가맹점 주문 ID
status	string	결제 상태 (CREATED, PAID, EXPIRED, ...)
amount	string	wei 단위 토큰 금액 — currency 사용 여부와 무관하게 항상 wei
tokenAddress	string	결제 토큰 컨트랙트 주소
tokenSymbol	string	토큰 심볼 (예: USDT)
tokenDecimals	number	토큰 소수점 자릿수 (amount 환산 시 사용)
currency	string|null	법정화폐 코드 — 결제 생성 시 currency를 지정한 경우만 존재
fiatAmount	number|null	원본 법정화폐 금액 (currency 단위) — 결제 생성 시 currency를 지정한 경우만 존재
tokenPrice	number|null	환산에 사용된 최근 1시간 평균 토큰 가격(TWAP) (currency 단위) — 결제 생성 시 currency를 지정한 경우만 존재
recipientAddress	string	가맹점 수취 주소
txHash	string|null	결제 트랜잭션 해시 (PAID 이후 존재)

금액 검증 시 단위 주의

사용자가 결제 요청 시 currency를 지정해 fiat 금액(예: 25.5 USD)으로 보냈더라도, 응답의 amount는 항상 wei 단위로 환산된 토큰 금액입니다. 가맹점 DB에 저장한 fiat 금액과 검증하려면 amount가 아니라 currency + fiatAmount를 비교해야 합니다. 자세한 검증 체크리스트는 위젯 가이드의 결제 결과 검증 섹션을 참고하세요.

상태 흐름

CREATED ──► PAID
CREATED ──► INVALID
CREATED ──► EXPIRED
CREATED ──► FAILED
PAID    ──► REFUND_SUBMITTED ──► REFUNDED

상태 설명

상태	설명	다음 액션
CREATED	결제 생성됨, 온체인 트랜잭션 대기	사용자가 결제 진행
PAID	온체인 결제 확인됨	없음 (종료 - 성공)
REFUND_SUBMITTED	환불 요청 제출됨 (개발 중)	REFUNDED 될 때까지 대기
REFUNDED	환불 완료됨 (개발 중)	없음 (종료)
INVALID	온체인 결제 검증 실패 (금액/토큰/수신자 불일치)	새 결제 생성
EXPIRED	만료 (5분 초과)	새 결제 생성
FAILED	트랜잭션 실패	새 결제 생성

온체인 동기화

GET /payments/:id 호출 시 블록체인과 DB 상태를 실시간으로 동기화합니다. 결제 성공 시 상태는 PAID(온체인 결제 확인, 자금이 상점으로 직접 전송됨)가 됩니다.

다음 단계

• 환불 - 결제 환불 처리
• 결제 동작 원리 - 가스리스 아키텍처
• 에러 코드 - 에러 처리