FAQ 및 트러블슈팅 (Troubleshooting)

연동 중 발생할 수 있는 주요 장애 상황과 해결 방안을 안내합니다.

자주 묻는 질문 (FAQ)

Q. 사용자가 최초 1회 Approve를 할 가스비(ETH/MATIC)가 아예 없으면 어떻게 하나요?

일반 ERC-20 토큰의 경우 approve()는 필연적으로 트랜잭션 가스비를 발생시킵니다. 해결 및 권장 방안:

1. Permit 지원 토큰 사용(강력 권장): USDC 등 EIP-2612 Permit을 기본 지원하는 ERC-20 토큰을 사용하시면, 최초 Approve도 Permit 서명으로 대체할 수 있어 100% 서명 기반으로 가스비 없이 운영이 가능합니다.
2. 가맹점 Faucet 운영: 가맹점 별도 서비스를 통해 신규 가입자에게 미량의 MATIC을 드롭해주는 방법이 있습니다만 개발/운영 비용이 수반됩니다.

Q. 결제 완료 이벤트를 Webhook으로 받지 못했어요.

네트워크 일시적 장애가 원인일 수 있습니다. 본 시스템 릴레이어는 Webhook 전송 실패 시(상태 200 OK 비수신 시) 일정 주기마다 **재시도(Retry)**를 수행합니다. 만일에 대비해, 가맹점 클라이언트(또는 서버) 측에 ‘결제 상태 새로고침’ 버튼 등을 두어 GET /payments/:id API를 폴링하는 안전장치를 구현해 두는 것을 권장합니다.

트러블슈팅

1. 서명 검증 실패 (INVALID_SIGNATURE 에러)

Relay API에 서명 제출 시 INVALID_SIGNATURE 응답이 발생하는 경우입니다. 체크포인트:

• EIP-712 데이터의 도메인 파라미터 중 chainId가 현재 사용자 메타마스크에 접속된 네트워크 체인 ID와 동일한지 확인하세요.
• 사용 중인 forwarderAddress 값이 API 결제 세션 응답에서 받은 값과 일치하는지 점검하세요.
• 서명 시 포함된 data 구조에 결제 금액, paymentId 등 하나라도 값이 변경될 경우 서명은 유효하지 않게 됩니다.

2. Relay 전송 후 Revert 발생 (결제 상태 FAILED)

릴레이어가 맴풀에 트랜잭션을 날렸으나 스마트 컨트랙트 단에서 Reverted가 나는 경우입니다. 체크포인트:

• Approve 부족: Permit을 지원하지 않는 토큰임에도 불구하고, 충분한 위임(allowance) 없이 가스리스 서명을 제출한 경우 발생합니다.
• 잔고 부족 (Insufficient Balance): 지갑에 보유한 토큰 잔액이 결제 금액보다 적을 경우 Revert 됩니다.
• Nonce 문제: 사용자가 아주 짧은 시간에 서명을 매크로급으로 여러 개 생성 전송하여, 이전 서명의 nonce가 다시 전송되었을 경우 릴레이가 거절합니다.

3. 클라이언트 오류 메세지

상황 A: "Unrecognized chain ID" 혹은 "지원하지 않는 네트워크"

사용자의 지갑이 Polygon Amoy 등이 아닌 이더리움 메인넷 등 다른 네트워크에 연결된 상태에서 서명을 시도한 것입니다.

• 해결 방안: wagmi의 useSwitchChain() 등을 사용해 서명 생성 전에 반드시 컨트랙트의 타깃 체인으로 네트워크 변경 프로토콜을 선행해야 합니다.

상황 B: "CORS error"

클라이언트 브라우저에서 Public Key(pk_xxx)를 사용하는 POST /payments 엔드포인트를 호출할 때 나타납니다.

• 해결 방안: 요청의 Origin 헤더 도메인이 관리자 측 화이트리스트에 올바르게 등록되지 않은 경우입니다. SoloPay 운영팀에 해당 도메인을 Origin 허용 도메인으로 추가 요청해 주세요.

기타 API 에러 코드

결제 세션 생성 및 Relay 요청 시 반환되는 수많은 상태 코드는 명확한 사유를 가지고 있습니다. 더 자세한 내용은 API 에러 코드 명세서를 확인하시기 바랍니다.