암호화폐 체크아웃은 어떤 이벤트를 발생시키나요?

InfraIO Pay는 상태 전환마다 하나의 웹훅을 발생시킵니다. 이 상태 머신은 의도적으로 작게 설계되어, 이행 로직을 정확히 하나의 이벤트에 연결하고 나머지는 무시할 수 있습니다.

  • payment.pending, 구매자가 트랜잭션을 브로드캐스트함; 컨펌이 계속 누적되는 중입니다.
  • payment.confirmed, 트랜잭션이 해당 네트워크의 컨펌 임계치에 도달했습니다.
  • payment.settled, 자금이 정산 지갑으로 스윕되었습니다. 여기서 이행하세요.
  • session.expired, 결제 없이 체크아웃 창이 닫혔습니다. 결코 청구되지 않습니다.

어떤 이벤트에서 이행해야 하나요?

payment.settled에서 이행하세요. pending 상태의 트랜잭션은 여전히 컨펌에 실패할 수 있고, 컨펌 임계치는 네트워크마다 다르므로, 그보다 이전 상태를 최종으로 취급하면 결코 도달하지 않을 결제에 대해 발송하는 위험을 감수하게 됩니다. 정산(settlement)은 그 자금이 되돌릴 수 없이 당신의 것이 되는 지점입니다.

구매자에게 진행 상황을 보여줘야 한다면 UI에서 pending과 confirmed를 표시해도 좋지만, 되돌릴 수 없는 작업(발송, 접근 권한 부여, 민팅)은 반드시 settled에 묶어두세요.

웹훅이 진짜인지 어떻게 검증하나요?

모든 웹훅은 여러분의 엔드포인트 시크릿으로 서명됩니다. raw 요청 본문 전체에 대해 HMAC을 다시 계산하고, 서명 헤더와 constant-time으로 비교하세요; 일치하지 않는 것은 모두 거부합니다. HMAC이 처음이라면 MDN의 SubtleCrypto.sign 레퍼런스가 좋은 입문서가 되고, Stripe의 웹훅 모범 사례 가이드는 운영 측면을 잘 다룹니다.

파싱하거나 처리하기 전에 검증하세요. 서명이 없거나 잘못 서명된 요청은 결코 비즈니스 로직에 도달해서는 안 됩니다.

전송을 안전하게 재시도할 수 있게 만드는 방법은?

웹훅은 최소 한 번(at-least-once) 전달되므로, 네트워크 오류 이후 같은 이벤트가 두 번 이상 도착할 수 있습니다. 각 이벤트는 idempotency key를 가지고 있습니다; 처리한 키를 기록하고 반복되는 경우 아무 동작도 하지 않으세요(no-op). 2xx를 빠르게 응답하고 느린 작업은 비동기로 처리해, 발신 측이 타임아웃되어 불필요하게 재시도하지 않도록 하세요. InfraIO는 전달 로그를 보관하며, 의도적으로 재처리가 필요한 경우 원클릭 replay를 제공합니다.