<!-- Source: https://docs.infraio.xyz/ko/checkout/overview -->
<!-- Last updated: 2026-10-04 -->

# 체크아웃 — 개요

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

## 세 가지 모드

- [팝업](https://docs.infraio.xyz/ko/sdks/javascript#popup) — 중앙 정렬 오버레이 팝업, 기본 ~560×780. 스토어프론트는 그대로 유지됩니다. 결제 후 팝업이 닫히면 `onSuccess`가 발생합니다. 기본 모드입니다.
- [리디렉션](https://docs.infraio.xyz/ko/sdks/javascript#redirect) — 체크아웃으로 하드 내비게이션. 팝업이 차단된 브라우저나 오버레이가 어색하게 느껴지는 모바일 웹에 적합합니다. 구매자는 세션의 `success_url` / `cancel_url`을 통해 돌아옵니다.
- [임베드](https://docs.infraio.xyz/ko/sdks/javascript#embed) — 가맹점 페이지 내부 iframe. 레이아웃을 처음부터 끝까지 제어하고 컨텍스트 전환을 원하지 않을 때 적합합니다. postMessage를 통해 자동 리사이즈됩니다.

## 모드 선택 가이드

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

## 구매자가 보는 것

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

1. **주문 요약**(라인 아이템, 합계, 통화). 이미 가맹점 측에서 표시한
   경우 `hideSummary`로 숨길 수 있습니다.
2. **자산 선택기** — 가맹점 설정에서 활성화한 체인 × 자산 조합 목록.
   구매자가 하나를 선택합니다.
3. 선택한 조합에 대한 **주문별 입금 주소 + QR + 금액**. 구매자는 스캔하거나,
   지갑을 연결하거나(WalletConnect 버튼), SDK를 통해 미리 연결된
   지갑에서 결제합니다. TRON, Solana, TON에서는 구매자가 가맹점의 지갑으로 직접 결제합니다. [지갑 직접 결제 네트워크](https://docs.infraio.xyz/ko/concepts/chains#지갑-직접-결제-네트워크)를 참조하세요.
4. **상태 펄스** — "송금 대기 중", "Tx 감지됨(3/12 confirmations)",
   "결제 완료".
5. **취소** 버튼(항상 표시) → `onCancel`을 트리거합니다.

## 페이지 커스터마이징

| 항목 | 방법 | 제한 |
| --- | --- | --- |
| 주문 요약 숨기기 | SDK의 `hideSummary: true` | 구매자는 입금 패널에서 합계를 여전히 볼 수 있음 |
| InfraIO Pay 헤더 숨기기 | SDK의 `hideHeader: true` | 완전한 화이트 라벨을 위해 `walletAddress`와 함께 사용 |
| 지갑 사전 연결 | `walletAddress` + `walletChainId` + `onSignRequest` | WalletConnect 모달을 우회 |
| 로케일 | 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`에서 저희 오리진을
허용해야 합니다.

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

iframe은 `allow="payment; clipboard-write"` 권한 정책을 가집니다 — Payment
Request API를 호출하고 클립보드에 쓸 수 있을 뿐, 그 이상은 아닙니다. iframe에
HTML `sandbox` 속성을 추가하지 마세요. 지갑 연결이 깨집니다. iframe은 크로스
오리진 경계와 여러분의 `frame-src` CSP로 격리됩니다.

## 모바일 고려사항

모바일 브라우저, 특히 Safari는 팝업을 자주 차단합니다. 트래픽이 대부분 모바일이라면
`mode: "redirect"`를 사용하세요. 작은 화면에서는 팝업 오버레이가 키보드 영역도
가려 자산 선택이 불편합니다.

## 화이트 라벨 브랜딩

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

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

## 다음 단계

- [SDK → JavaScript](https://docs.infraio.xyz/ko/sdks/javascript) — 모드별 전체 옵션 레퍼런스.
- [개념 → 세션](https://docs.infraio.xyz/ko/concepts/sessions) — 구매자가 페이지에 있는 동안
  서버 측에서 일어나는 일.
- [개념 → 체인 및 자산](https://docs.infraio.xyz/ko/concepts/chains) — 선택기에서 사용 가능한
  체인 × 자산 조합.