SDK popup và mã mẫu

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

# SDK popup và mã mẫu

SDK mở cửa sổ ngay trong thao tác bấm của người mua để giảm nguy cơ bị trình duyệt chặn. Sau khi backend tạo phiên, SDK điều hướng popup sang form ePay. Không lồng iframe thanh toán trong trang bán hàng.

```html
<script src="https://payment.pay2s.vn/sdk/pay2s-card.js"></script>
<button id="pay">Thanh toán thẻ</button>
```

```js
document.getElementById('pay').onclick = async () => {
  try {
    await Pay2SCard.open({
      createSession: async () => {
        // Endpoint backend của bạn xác thực người mua và lấy số tiền từ đơn.
        const r = await fetch('/checkout/card-session', {method:'POST'});
        if (!r.ok) throw new Error('Không tạo được phiên');
        return r.json(); // data của API Pay2S: sessionId, orderId, expiresAt, popupUrl
      },
      getStatus: async ({orderId}) => {
        const r = await fetch('/checkout/card-status', {
          method:'POST', headers:{'Content-Type':'application/json'},
          body:JSON.stringify({orderId})
        });
        if (!r.ok) throw new Error('Chưa kiểm tra được trạng thái');
        return r.json(); // data của API tra cứu Pay2S
      },
      onStatus: data => console.log(data.status), // chỉ cập nhật giao diện
      onClose: () => console.log('Popup đã đóng; tiếp tục kiểm tra backend')
    });
  } catch (e) { alert(e.message); }
};
```

`getStatus` là bắt buộc. Nó giữ luồng cập nhật hoạt động khi trình duyệt hoặc trang ePay làm mất liên kết `window.opener`. Thông báo từ popup chỉ kích hoạt kiểm tra lại backend; không tự xác nhận đơn.

`open()` trả `{sessionId, close}`. `close()` đóng cửa sổ, không hủy thanh toán. Không tạo lại đơn hoặc trừ tiền dựa vào việc cửa sổ đóng. Khi popup bị chặn, SDK báo lỗi trước khi gọi `createSession`.

## Tải từng file mẫu

- [Backend Node.js](/downloads/card-popup/server.cjs)
- [Trang HTML mẫu](/downloads/card-popup/index.html)
- [README tích hợp](/downloads/card-popup/README.txt)
- [Hướng dẫn tiếng Việt](/downloads/card-popup/HUONG-DAN.txt)
- [OpenAPI JSON](/downloads/card-popup/openapi.json)

Node 20 trở lên, không cần cài thư viện cho bản mẫu. Cấu hình `PAY2S_PARTNER_CODE`, `PAY2S_ACCESS_KEY`, `PAY2S_SECRET_KEY`, `MERCHANT_ORIGIN`, `MERCHANT_WEBHOOK_URL`, rồi chạy `node server.cjs`. Đặt dịch vụ sau tên miền HTTPS trùng origin đã khai báo.

Bản mẫu có giá cố định 2.000 VND, chỉ lưu webhook vào inbox, không giao hàng. Khi tích hợp thực tế, bổ sung đăng nhập, kiểm tra quyền sở hữu đơn, giao dịch cơ sở dữ liệu chống xử lý trùng và đối chiếu số tiền.

[Trải nghiệm ngay](/demos/card-popup/) · [API Playground](/playground/card-popup/)

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