API tạo phiên thẻ

✧ Mở bằng AI

Sao chép tài liệu, mở AI rồi dán vào cuộc trò chuyện.

POST https://payment.pay2s.vn/api/card-popup-session.php

Dùng header xác thực HMAC. API tạo đơn thẻ mới, không yêu cầu tài khoản ngân hàng hoặc tạo mã QR trước.

{
  "action": "create",
  "orderId": "ORDER001",
  "amount": 100000,
  "cardBrand": "visa",
  "buyer": {"firstName": "An", "lastName": "Nguyen", "email": "[email protected]"},
  "merchantOrigin": "https://shop.example.com",
  "webhookUrl": "https://shop.example.com/pay2s/webhook",
  "sandboxOnly": true
}

Trường	Quy tắc
action	`create`, có thể bỏ qua
orderId	Bắt buộc; 1–128 ký tự chữ/số hoặc `._:-`
amount	Số nguyên VND, từ 2.000 đến 2.147.483.646
cardBrand	visa, mastercard, jcb, amex, unionpay
buyer.firstName / lastName	Mỗi ô 1–30 ký tự; chữ, dấu, khoảng trắng, dấu chấm/gạch nối
buyer.email	Email hợp lệ, tối đa 40 ký tự theo ePay
merchantOrigin	HTTPS và tên miền, không có đường dẫn/query/fragment
webhookUrl	HTTPS công khai, không trỏ vào mạng nội bộ
sandboxOnly	Boolean, mặc định false; true bắt buộc kết nối sandbox

Phản hồi

{
  "status": true,
  "message": "OK",
  "data": {
    "sessionId": "<64 ký tự hex>",
    "orderId": "ORDER001",
    "environment": "sandbox",
    "expiresAt": 1792300000,
    "popupUrl": "https://payment.pay2s.vn/sdk/card-popup.html#<TOKEN>"
  }
}

Phiên có thời hạn 15 phút. popupUrl là thông tin truy cập phiên: chỉ trả cho người mua được phép thanh toán đơn, không ghi log hay công khai. Không đưa secret merchant xuống frontend.

Chống tạo trùng

Cùng phạm vi tài khoản/cửa hàng và cùng orderId, nội dung giống nhau trả lại phiên cũ. Khác số tiền, loại thẻ, người mua, origin, webhook hoặc sandboxOnly trả lỗi xung đột. Đơn cũ ngoài luồng popup không được chuyển ngầm sang luồng này.

Timeout: gọi lại cùng nội dung, cùng mã đơn. Không tạo mã mới để thử lại khi chưa biết kết quả đơn trước. Phiên đã mở không gửi lại form ePay khi tải lại hoặc mở lại popup.

Lỗi

HTTP	Ý nghĩa thường gặp
403	API popup chưa bật
409	Sai chữ ký, timestamp hết hạn, xung đột mã đơn, dữ liệu/điều kiện thanh toán không hợp lệ
413	Body vượt 32 KB
429	Quá nhiều yêu cầu
503	Dịch vụ chưa sẵn sàng; giữ mã đơn và kiểm tra lại

Lỗi có status:false, message, có thể kèm data.reference. Không dựa vào nội dung thông báo lỗi để đánh dấu thanh toán thất bại.

Thử API · SDK mở popup

Chọn kết nối

Truyền connectionId (số nguyên dương) đã lưu vào body tạo phiên. Không cần gọi danh sách mỗi lần. Bỏ trường này để dùng mặc định. Xem danh sách kết nối. ID là một phần nội dung chống trùng; không đổi ID khi gửi lại cùng orderId.