Checkout API

Ask AI

Tạo một phiên thanh toán (checkout session) để chuyển hướng người mua đến trang thanh toán do GLODIPAY lưu trữ hoặc nhận liên kết thanh toán có thể chia sẻ.

Endpoint: POST /v2/checkout 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	(Các) phương thức thanh toán hiển thị. Ví dụ: checkout. Xem Phương thức thanh toán
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
connectionMode	String	O	API (Mặc định) hoặc DIRECT_POST. Xem Chế độ kết nối
orderDescription	String(max:3000)	M	Mô tả ngắn gọn hiển thị trên màn hình thanh toán. 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"}]
paymentFilter	JSON	O	Mảng các loại phương thức thanh toán cần loại trừ khỏi phiên. Ví dụ: ["card"]
paymentSorter	JSON	O	Mảng có thứ tự để kiểm soát thứ tự hiển thị. Ví dụ: ["checkout","card"]
feeBySeller	Number(0–100)	O	% phí xử lý do người bán trả. 0 = người mua trả 100%. Ví dụ: 50
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
billingEmail	String(max:255)	O	Địa chỉ email người mua. Ví dụ: john.doe@example.com
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
billingCountry	String	O	Mã quốc gia ISO 3166-1 alpha-2. Ví dụ: US. Xem Mã quốc gia
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
brandName	String(1–255)	O	Ghi đè tên thương hiệu trên màn hình thanh toán. 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 màn hình thanh toán. 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)

connectionMode: API

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
paymentLink	String	URL đã ký — chuyển hướng người mua đến URL này để hoàn tất thanh toán
message	String	Thông báo dễ hiểu cho người dùng

Thành công:

{
  "status": "created",
  "transactionId": "01jza90dy6w82dfrrqvadn5vs4",
  "paymentLink": "https://payment.gpayprocessing.com/v2/checkout/01jza90dy6w82dfrrqvadn5vs4?...",
  "message": "Payment Link created successfully"
}

Lỗi:

{
  "status": "error",
  "transactionId": null,
  "paymentLink": null,
  "message": "No active payment service providers found. Please contact support."
}

connectionMode: DIRECT_POST

Trình duyệt của người mua được chuyển hướng trực tiếp đến trang thanh toán do GLODIPAY lưu trữ. Không có phản hồi JSON nào được trả về máy chủ của bạn.

---

URL gọi lại (Callback URL)

Sau khi thanh toán, GLODIPAY thực hiện chuyển hướng GET đến callbackUrl của bạn với tham số truy vấn payload:

GET {callbackUrl}?payload={base64-encoded-json}

Các trường payload sau khi giải mã:

Trường	Loại	Mô tả
status	String	Trạng thái giao dịch cuối cùng. Xem Giá trị trạng thái
transactionId	String	ID giao dịch của GLODIPAY
ref	String	orderRef của người bán
amount	Float	Số tiền hóa đơn
currency	String	Mã tiền tệ
signature	String	Chữ ký RSA-MD5 — xác minh bằng khóa công khai của GLODIPAY

Luôn xác minh signature trong payload gọi lại trước khi tin tưởng vào status. Sử dụng endpoint Truy vấn Giao dịch (Transaction Query) để lấy thông tin thanh toán đầy đủ.

---

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