iFrame Card API
Tạo một phiên làm việc để nhận URL đã ký trỏ tới biểu mẫu nhập thẻ do GLODIPAY lưu trữ. Nhúng URL này vào một <iframe> trên trang của bạn — người mua sẽ nhập chi tiết thẻ vào biểu mẫu được lưu trữ mà không cần rời khỏi trang web của bạn.
Endpoint: POST /v2/card/iframe
Content-Type: application/json
Tham số yêu cầu (Request Parameters)
| Trường | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
| merchantId | String(1–50) | M | ID của người bán (Merchant ID). Ví dụ: 1100000123 |
| orderRef | String(1–250) | M | Mã tham chiếu giao dịch duy nhất cho mỗi người bán. Ví dụ: ORDER-2026-001 |
| amount | Float | M | Số tiền hóa đơn. Tối thiểu: 1. Tối đa 2 chữ số thập phân. Ví dụ: 100.00 |
| currency | String(3) | M | Mã tiền tệ ISO 4217. Ví dụ: USD |
| paymentMethod | String | M | Phải là card |
| callbackUrl | String(1–300) | M | URL chuyển hướng sau khi thanh toán thành công. Phải là https. Ví dụ: https://yoursite.com/return |
| notificationUrl | String(1–300) | M | Endpoint máy chủ của bạn để nhận webhook IPN. Phải là https. Ví dụ: https://yoursite.com/webhook |
| cancelUrl | String(1–300) | M | URL chuyển hướng khi hủy bỏ. Phải là https. Ví dụ: https://yoursite.com/cancel |
| errorUrl | String(1–300) | M | URL chuyển hướng khi có lỗi. Phải là https. Ví dụ: https://yoursite.com/error |
| billingEmail | String(max:255) | O | Địa chỉ email người mua. Ví dụ: john.doe@example.com |
| billingCountry | String | O | Mã quốc gia ISO 3166-1 alpha-2. Ví dụ: US. Xem Mã quốc gia |
| billingFirstName | String(max:255) | O | Tên (First name) thanh toán. Ví dụ: John |
| billingLastName | String(max:255) | O | Họ (Last name) thanh toán. Ví dụ: Doe |
| billingStreet1 | String(max:255) | O | Địa chỉ đường phố dòng 1. Ví dụ: 123 Main St |
| billingStreet2 | String(max:255) | O | Địa chỉ đường phố dòng 2. Ví dụ: Suite 4B |
| billingCity | String(max:255) | O | Thành phố. Ví dụ: New York |
| billingState | String(2–255) | O | Bang / Tỉnh. Ví dụ: NY |
| billingPostalCode | String(max:25) | O | Mã bưu điện / ZIP. Ví dụ: 10001 |
| billingPhoneCountryCode | String(max:10) | O | Mã vùng quốc gia của điện thoại. Ví dụ: 1 cho Mỹ |
| billingPhoneNumber | String(max:20) | O | Số điện thoại. Ví dụ: 5551234567 |
| orderDescription | String(max:3000) | M | Mô tả ngắn gọn về đơn hàng. Ví dụ: Order #2026-001 |
| metadata | JSON | O | Cặp khóa-giá trị được trả về trong IPN và phản hồi truy vấn. Ví dụ: {"orderId":"12345"} |
| transactionDocuments | JSON | O | Các tài liệu hỗ trợ cho giao dịch. Ví dụ: [{"type":"invoice","url":"https://yoursite.com/inv.pdf"}] |
| feeBySeller | Number(0–100) | O | % phí xử lý do người bán trả. 0 = người mua trả 100%. Ví dụ: 50 |
| brandName | String(1–255) | O | Ghi đè tên thương hiệu trên biểu mẫu thẻ. Ví dụ: My Store |
| colorMode | String(1–255) | O | Tối đa 3 màu cách nhau bởi ---. Chấp nhận tên màu, HEX hoặc RGBA. Ví dụ: #2e7d32---#e8f5e9---#81c784 |
| logoSource | String(1–255) | O | Ghi đè logo trên biểu mẫu thẻ. Ví dụ: https://yoursite.com/logo.png |
| customerIp | String | O | Địa chỉ IP của khách hàng. Ví dụ: 203.0.113.42 |
| websiteUrl | String(max:300) | O | URL trang web của người bán. Ví dụ: https://yoursite.com |
| expiresAt | String | O | Thời gian hết hạn phiên ở định dạng ISO 8601. Mặc định: 24 giờ. Ví dụ: 2026-04-22T10:00:00+00:00 |
| signature | String(max:750) | M | Chữ ký RSA-MD5. Xem Chữ ký |
M = Bắt buộc (Mandatory), O = Tùy chọn (Optional)
Phản hồi (Response)
| Trường | Loại | Mô tả |
|---|---|---|
| status | String | created khi thành công, error khi thất bại |
| transactionId | String (ULID) | ID giao dịch của GLODIPAY |
| url | String | URL đã ký trỏ đến biểu mẫu nhập thẻ được lưu trữ — nhúng trong <iframe> |
| message | String | Thông báo dễ hiểu cho người dùng |
Thành công:
{
"status": "created",
"transactionId": "01jza90dy6w82dfrrqvadn5vs4",
"url": "https://payment.gpayprocessing.com/v2/card-iframe/01jza90dy6w82dfrrqvadn5vs4?...",
"message": "Iframe card created successfully"
}
Lỗi:
{
"status": "error",
"transactionId": null,
"url": null,
"message": "No active payment service providers found. Please contact support."
}
Nhúng iFrame
Sau khi nhận được url, hãy nhúng nó vào trang của bạn:
<iframe
src="{url}"
width="100%"
height="600"
frameborder="0"
scrolling="no"
allowtransparency="true">
</iframe>
URL đã được ký và sẽ hết hạn tại
expiresAt. Người mua phải hoàn tất thanh toán trong thời gian hết hạn phiên. Không lưu trữ hoặc chia sẻ URL ngoài phiên thanh toán hiện tại.
Thông báo IPN
GLODIPAY gửi kết quả thanh toán đến notificationUrl của bạn khi giao dịch đạt đến trạng thái cuối cùng. Xem Thông báo IPN để biết định dạng đầy đủ của payload và phản hồi xác nhận.
Truy vấn giao dịch (Transaction Query)
Sử dụng POST /v2/checkout/query để kiểm tra trạng thái của giao dịch bất kỳ lúc nào. Xem Truy vấn giao dịch.
Nguồn
Trang này được bắt nguồn từ GLODIPAY_iFrame_API_Specification_v2.