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

# Checkout — Tổng quan

**Trang thanh toán dựng sẵn** là trang mà người mua thực sự gửi tiền.
Bạn không tự render asset picker, địa chỉ nhận tiền riêng cho từng đơn, hay QR — SDK mở
trang của chúng tôi (tại `https://checkout.infraio.xyz/<session_key>`)
và chúng tôi xử lý UI.

## Ba chế độ

- [Popup](https://docs.infraio.xyz/vi/sdks/javascript#popup) — Popup overlay căn giữa, mặc định ~560×780. Storefront giữ nguyên. `onSuccess` được phát khi popup đóng sau thanh toán. Chế độ mặc định.
- [Redirect](https://docs.infraio.xyz/vi/sdks/javascript#redirect) — Điều hướng cứng đến checkout. Tốt nhất cho trình duyệt chặn popup hoặc mobile web nơi overlay cảm thấy khó chịu. Người mua quay lại qua `success_url` / `cancel_url` từ session.
- [Embed](https://docs.infraio.xyz/vi/sdks/javascript#embed) — iframe bên trong trang của bạn. Tốt nhất khi bạn kiểm soát layout đầu cuối và muốn không có chuyển ngữ cảnh. Tự resize qua postMessage.

## Heuristic chọn chế độ

| Nếu… | Dùng |
| --- | --- |
| Desktop web, e-commerce mặc định | **Popup** |
| Mobile web | **Redirect** (popup thường bị chặn trên mobile) |
| Admin panel bị khóa CSP nghiêm ngặt | **Redirect** |
| Webview trong app / native checkout-in-a-page | **Embed** |
| Bạn muốn luồng người mua hoàn toàn tùy chỉnh với header white-label | **Embed** + `hideHeader` + wallet connect của riêng bạn |

## Người mua thấy gì

Bất kể chế độ nào, trang đều surface:

1. **Tóm tắt order** (line items, total, currency). Ẩn bằng
   `hideSummary` nếu bạn đã hiển thị nó ở phía mình.
2. **Asset picker** — danh sách các cặp chain × asset bạn đã enable
   trong cài đặt merchant. Người mua chọn một.
3. **Địa chỉ nhận tiền riêng cho từng đơn + QR + amount** cho cặp đã chọn. Người mua hoặc
   quét, kết nối ví (nút WalletConnect), hoặc trả từ ví đã kết nối
   sẵn mà bạn cung cấp qua SDK. Trên TRON, Solana và TON, người mua trả thẳng vào ví của bạn; xem [Network thanh toán thẳng vào ví](https://docs.infraio.xyz/vi/concepts/chains#network-thanh-toán-thẳng-vào-ví).
4. **Status pulse** — "Waiting for transfer", "Tx detected (3/12
   confirmations)", "Paid".
5. Nút **Cancel** (luôn hiển thị) → kích hoạt `onCancel`.

## Tùy chỉnh trang

| Knob | Cách | Giới hạn |
| --- | --- | --- |
| Ẩn tóm tắt order | `hideSummary: true` trên SDK | Người mua vẫn thấy total trong panel deposit |
| Ẩn header InfraIO Pay | `hideHeader: true` trên SDK | Kết hợp với `walletAddress` để white-label đầy đủ |
| Kết nối ví trước | `walletAddress` + `walletChainId` + `onSignRequest` | Bỏ qua modal WalletConnect |
| Ngôn ngữ | `locale` trên SDK — một trong `en`, `vi`, `ja`, `ko`, `es`, `pt-BR`, `ru`, `tr`, `zh-CN`, `zh-TW` | Địa phương hóa trang checkout **và** trang refund (cùng modal kết nối ví). Không xác định hoặc bỏ trống → về `en` |
| Logo, brand color | **Dashboard merchant → Branding** | Áp dụng toàn cục, không phải theo session |

## Hành vi return URL

Với chế độ **redirect**, người mua luôn quay về một trong:

- `success_url` từ session (khi thanh toán settled)
- `cancel_url` từ session (khi cancel/từ bỏ)
- Nếu bạn không set chúng, SDK fallback về trang đã mở checkout, với
  `?session_id=…&status=success|cancel` được nối thêm

Với chế độ **popup** và **embed** không có điều hướng — quyền điều
khiển trả về trang của bạn qua `onSuccess` / `onCancel`. Dùng chúng
để quyết định UI hiển thị tiếp theo.

## CSP và embedding

Nếu bạn dùng chế độ **embed**, CSP phải cho phép origin của chúng tôi
trong `frame-src`:

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

iframe mang permissions policy `allow="payment; clipboard-write"` — nó
có thể gọi Payment Request API và ghi vào clipboard, không hơn. Đừng
thêm thuộc tính HTML `sandbox` vào iframe, vì nó làm hỏng việc kết nối
ví. iframe được isolation bởi ranh giới cross-origin và CSP
`frame-src` của bạn.

## Cân nhắc trên mobile

Trình duyệt mobile, đặc biệt là Safari, thường chặn popup. Nếu lưu lượng
của bạn chủ yếu là mobile, hãy dùng `mode: "redirect"`. Trên màn hình
nhỏ, overlay popup cũng che vùng bàn phím, khiến việc chọn tài sản
vụng về.

## White-label branding

White-label đầy đủ yêu cầu:

1. `hideHeader: true` trên SDK
2. `walletAddress` kết nối sẵn (người mua không thấy WalletConnect)
3. Logo + brand color của bạn set trong branding của merchant dashboard
4. (Tùy chọn) Custom domain cho trang checkout —
   `pay.your-shop.com` thay vì `checkout.infraio.xyz`. Thiết lập trong
   dashboard sau khi CNAME của bạn được xác thực.

## Tiếp theo

- [SDK → JavaScript](https://docs.infraio.xyz/vi/sdks/javascript) — tham chiếu option đầy đủ
  theo từng chế độ.
- [Khái niệm → Sessions](https://docs.infraio.xyz/vi/concepts/sessions) — điều gì đang xảy ra
  phía server trong khi người mua ở trên trang.
- [Khái niệm → Chains & tài sản](https://docs.infraio.xyz/vi/concepts/chains) — những cặp
  chain×asset nào có trong picker.