Skip to Content
체크아웃개요

체크아웃 — 개요

호스팅 체크아웃은 구매자가 실제로 자금을 전송하는 페이지입니다. 자산 선택기, 입금 주소, QR 코드를 가맹점이 직접 렌더링할 필요가 없습니다 — SDK가 저희 페이지(https://checkout.infraio.xyz/<session_key>)를 열고 저희가 UI를 처리합니다.

세 가지 모드

중앙 정렬 오버레이 팝업, 기본 ~560×780. 스토어프론트는 그대로 유지됩니다. 결제 후 팝업이 닫히면 onSuccess가 발생합니다. 기본 모드입니다.

팝업

체크아웃으로 하드 내비게이션. 팝업이 차단된 브라우저나 오버레이가 어색하게 느껴지는 모바일 웹에 적합합니다. 구매자는 세션의 success_url / cancel_url을 통해 돌아옵니다.

리디렉션

가맹점 페이지 내부 iframe. 레이아웃을 처음부터 끝까지 제어하고 컨텍스트 전환을 원하지 않을 때 적합합니다. postMessage를 통해 자동 리사이즈됩니다.

임베드

모드 선택 가이드

조건사용
데스크톱 웹, 기본 이커머스팝업
모바일 웹리디렉션 (팝업 + 모바일 = 안 좋음)
CSP가 엄격히 잠긴 어드민 패널리디렉션
인앱 웹뷰 / 페이지 내 네이티브 체크아웃임베드
화이트 라벨 헤더로 완전한 커스텀 구매자 흐름이 필요한 경우임베드 + hideHeader + 자체 지갑 연결

구매자가 보는 것

모드에 관계없이 페이지에는 다음이 표시됩니다.

  1. 주문 요약(라인 아이템, 합계, 통화). 이미 가맹점 측에서 표시한 경우 hideSummary로 숨길 수 있습니다.
  2. 자산 선택기 — 가맹점 설정에서 활성화한 체인 × 자산 조합 목록. 구매자가 하나를 선택합니다.
  3. 선택한 조합에 대한 입금 주소 + QR + 금액. 구매자는 스캔하거나, 지갑을 연결하거나(WalletConnect 버튼), SDK를 통해 미리 연결된 지갑에서 결제합니다.
  4. 상태 펄스 — “송금 대기 중”, “Tx 감지됨(3/12 confirmations)”, “결제 완료”.
  5. 취소 버튼(항상 표시) → onCancel을 트리거합니다.

페이지 커스터마이징

항목방법제한
주문 요약 숨기기SDK의 hideSummary: true구매자는 입금 패널에서 합계를 여전히 볼 수 있음
InfraIO 헤더 숨기기SDK의 hideHeader: true완전한 화이트 라벨을 위해 walletAddress와 함께 사용
지갑 사전 연결walletAddress + walletChainId + onSignRequestWalletConnect 모달을 우회
로케일SDK의 locale — en, vi, ja, ko, es, pt-BR, ru, tr, zh-CN, zh-TW 중 하나체크아웃 및 환불 페이지(그리고 지갑 연결 모달)를 현지화합니다. 알 수 없거나 생략된 경우 → en으로 대체
로고, 브랜드 컬러가맹점 대시보드 → Branding세션이 아닌 전역 적용

리턴 URL 동작

리디렉션 모드의 경우 구매자는 항상 다음 중 하나로 돌아옵니다.

  • 세션의 success_url(정산된 결제의 경우)
  • 세션의 cancel_url(취소/포기의 경우)
  • 이를 설정하지 않은 경우 SDK는 체크아웃을 연 페이지로 폴백하며, ?session_id=…&status=success|cancel이 추가됩니다.

팝업과 임베드 모드에서는 내비게이션이 없습니다 — onSuccess / onCancel을 통해 가맹점 페이지로 제어가 반환됩니다. 이를 사용하여 다음에 표시할 UI를 결정하세요.

CSP 및 임베딩

임베드 모드를 사용하는 경우 가맹점 CSP는 frame-src에서 저희 오리진을 허용해야 합니다.

Content-Security-Policy:
  frame-src https://checkout.infraio.xyz https://checkout-dev.infraio.xyz;

iframe은 allow="payment; clipboard-write" 권한 정책을 가집니다 — Payment Request API를 호출하고 클립보드에 쓸 수 있을 뿐, 그 이상은 아닙니다. HTML sandbox 속성은 적용되어 있지 않습니다. 체크아웃 페이지는 지갑에 연결하는 완전한 앱이며, 그 postMessage 보안(양측의 오리진 검사)과 서드파티 지갑 SDK(WalletConnect, Coinbase, MetaMask)는 실제 동일 오리진 스크립팅 컨텍스트를 필요로 하므로, HTML sandbox 속성을 적용하면 미미한 격리 이득 대비 지갑 연결이 깨집니다. 대신 격리는 크로스 오리진 경계, 엄격한 postMessage 오리진 검사, 그리고 여러분의 frame-src CSP를 통해 이루어집니다.

모바일 고려사항

팝업은 모바일 Safari에서 적극적으로 차단됩니다. 트래픽이 대부분 모바일이라면 mode: "redirect"를 기본값으로 설정하세요. 팝업 오버레이는 작은 화면에서 키보드 영역도 가립니다 — 금액 입력에는 괜찮지만 자산 선택에는 어색합니다.

브랜딩(화이트 라벨용)

완전한 화이트 라벨에는 다음이 필요합니다.

  1. SDK의 hideHeader: true
  2. walletAddress 사전 연결(구매자는 WalletConnect를 보지 않음)
  3. 가맹점 대시보드 브랜딩에 설정된 로고 + 브랜드 컬러
  4. (선택) 체크아웃 페이지의 커스텀 도메인 — checkout.infraio.xyz 대신 pay.your-shop.com. CNAME이 검증되면 대시보드를 통해 셀프 서비스로 설정할 수 있습니다.

다음 단계

체인 및 자산개요