Skip to Content
CheckoutTổng quan

Checkout — Tổng quan

Checkout do hệ thống host là trang mà người mua thực sự gửi tiền. Bạn không tự render asset picker, địa chỉ deposit, 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 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.

Popup

Đ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.

Redirect

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.

Embed

Heuristic chọn chế độ

Nếu…Dùng
Desktop web, e-commerce mặc địnhPopup
Mobile webRedirect (popup + mobile = buồn)
Admin panel bị khóa CSP nghiêm ngặtRedirect
Webview trong app / native checkout-in-a-pageEmbed
Bạn muốn luồng người mua hoàn toàn tùy chỉnh với header white-labelEmbed + 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ỉ deposit + 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.
  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

KnobCáchGiới hạn
Ẩn tóm tắt orderhideSummary: true trên SDKNgười mua vẫn thấy total trong panel deposit
Ẩn header InfraIOhideHeader: true trên SDKKết hợp với walletAddress để white-label đầy đủ
Kết nối ví trướcwalletAddress + walletChainId + onSignRequestBỏ 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 colorDashboard 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:

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. iframe không bị HTML-sandbox: trang checkout là một app kết nối ví đầy đủ mà bảo mật postMessage của nó (kiểm tra origin ở cả hai phía) và các wallet SDK bên thứ ba (WalletConnect, Coinbase, MetaMask) đòi hỏi một scripting context same-origin thực sự, nên thuộc tính sandbox HTML sẽ phá vỡ wallet connect để đổi lấy lợi ích isolation không đáng kể. Isolation thay vào đó đến từ ranh giới cross-origin, kiểm tra origin postMessage nghiêm ngặt, và CSP frame-src của bạn.

Cân nhắc trên mobile

Popup bị chặn quyết liệt trên mobile Safari. Nếu lưu lượng của bạn chủ yếu là mobile, mặc định dùng mode: "redirect". Overlay popup cũng che vùng bàn phím trên màn hình nhỏ — ổn cho nhập số tiền, vụng về cho chọn tài sản.

Branding (cho nhóm white-label)

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. Self-serve qua dashboard sau khi CNAME của bạn được xác thực.

Tiếp theo

Chains & tài sảnTổng quan