Thanh toán thẻ popup

Nội dung Markdown đầy đủ của trang tài liệu.

# Thanh toán thẻ popup

Mở form nhập thẻ ePay trong khung nổi trên trang khách từ website của bạn. Pay2S giữ kết nối với ePay, xác minh IPN và gửi webhook về backend của bạn. Không cần tạo QR hay đưa khách qua trang chọn phương thức Pay2S.

[Thử API trong Playground](/playground/card-popup/) · [Trải nghiệm sandbox](/demos/card-popup/) · [Tải OpenAPI JSON](/downloads/card-popup/openapi.json)

## Luồng tích hợp

1. Backend của bạn xác thực khách hàng, lấy đơn và số tiền từ cơ sở dữ liệu.
2. Gọi API tạo phiên Pay2S bằng chữ ký HMAC, trả thông tin phiên cho trình duyệt.
3. SDK mở khung nổi chứa form ePay. Người mua nhập thông tin thẻ tại ePay.
4. ePay gửi IPN đến Pay2S; Pay2S xác minh và truy vấn kết quả phía ePay.
5. Backend của bạn nhận webhook Pay2S hoặc tra cứu trạng thái để hoàn tất đơn một lần.

Hỗ trợ Visa, Mastercard, JCB, AMEX và UnionPay. Bộ này dành cho thẻ; ví điện tử, POS và auto debit là các luồng khác.

## Điều kiện

- Tài khoản có gói Basic trở lên còn hạn; tài khoản demo được miễn điều kiện gói.
- Đã cấu hình kết nối và bật loại thẻ tại đúng tài khoản/cửa hàng.
- Production cần phạm vi website/cửa hàng được duyệt. Tài khoản demo không được dùng production.
- Pay2S đã bật API popup. Backend merchant và URL nhận webhook dùng HTTPS.

Playground sử dụng kết nối demo giữ ở server và gửi `sandboxOnly: true`. API từ chối nếu kết nối được chọn là production. Không nhập thẻ thật trong trang trải nghiệm.

## Trạng thái và tác dụng

Tạo phiên chưa thu tiền. Popup đóng chưa đồng nghĩa hủy. `paid` chỉ được ghi sau bước xác minh ở backend. Trạng thái `pending` hoặc `review` không được chuyển thành thất bại chỉ vì hết thời gian chờ.

Bộ này không yêu cầu xuất hóa đơn điện tử tự động. Mọi xử lý giao hàng, doanh thu hoặc hóa đơn của merchant cần dựa trên kết quả backend đã xác minh.

[Xác thực](/docs/card-popup/authentication/) · [Tạo phiên](/docs/card-popup/create-session/) · [Tra cứu](/docs/card-popup/status/) · [SDK](/docs/card-popup/sdk/) · [Webhook](/docs/card-popup/webhook/)

## Hiển thị ngay trong website

SDK mặc định dùng `display: "modal"`: khung nổi trong trang, không mở cửa sổ trình duyệt và không thay đổi URL website khách. Không cần thay chữ ký API hay luồng webhook. `merchantOrigin` phải đúng origin website nhúng. SDK xác minh thông điệp với frame và origin; kết quả vẫn lấy qua backend.

Có thể truyền `display: "popup"` nếu chủ động cần cửa sổ riêng. Đóng khung hoặc nhấn Escape không hủy giao dịch; SDK tiếp tục tra cứu. Website có CSP cần cho phép script-src và frame-src https://payment.pay2s.vn. Các chính sách nhúng/3DS của nhà cung cấp cần được kiểm thử trên tên miền thật.