THÔNG SỐ KỸ THUẬT API GLODIPAY

PHIÊN BẢN 2.0.0

Mục lục

• Giới thiệu
• Điểm cuối (Endpoints)
• Chữ ký (Signature)
• Thông số kỹ thuật API
  • POST PAYMENT (Checkout V2)
  • SERVER TO SERVER -- S2S Card V2
  • CARD IFRAME V2
  • TRANSACTION QUERY (Truy vấn giao dịch)
  • NOTIFICATION (Transaction IPN)
  • REFUND API (API Hoàn tiền)
  • REFUND QUERY (Truy vấn hoàn tiền)
  • REFUND NOTIFICATION (Refund IPN)
• Mô phỏng thanh toán (Thẻ thử nghiệm)

Sử dụng môi trường Thử nghiệm (Test). Không có chi phí thực tế nào được tính.

Không có 3DS	4111 1111 1111 1111	01/30	029	—
Không có 3DS	5555 5555 5555 4444	01/30	029	—
Thanh toán 3DS	4012 8888 8888 1881	01/30	029	Thành công: 123456 / Thất bại: 111111
Thanh toán 3DS	5111 1111 1111 1118	01/30	029	Thành công: 123456 / Thất bại: 111111
Thanh toán 3DS	4141 4141 4141 4141	12/30	123	Thành công: 123456 / Thất bại: 111111

• Phụ lục
  • Phương thức thanh toán
  • Chế độ kết nối
  • Giá trị trạng thái
  • Mã trạng thái
  • Mã tiền tệ
  • Mã quốc gia
  • Loại thẻ
• Ví dụ mã nguồn
  • PHP
  • Node.js

Giới thiệu

Tài liệu này mô tả GLODIPAY API v2, hỗ trợ người bán chấp nhận thẻ tín dụng/thẻ ghi nợ, ngân hàng di động, mã QR, ví điện tử và tiền điện tử trong một nền tảng thanh toán thống nhất duy nhất.

Điểm mới trong v2:

• Đa PSP (Nhà cung cấp dịch vụ thanh toán): Một phiên thanh toán (checkout session) có thể hiển thị đồng thời các phương thức thanh toán từ nhiều PSP. Người mua thấy tất cả các phương thức thanh toán có sẵn trên trang thanh toán được lưu trữ -- người bán không cần thực hiện thêm công việc nào.
• Tự động chuyển tầng (Auto-Cascade) cho S2S: Khi is_auto_cascade được bật, gateway sẽ tự động thử lại việc tính phí thẻ qua nhiều PSP trước khi trả về kết quả cuối cùng.
• Chế độ Payment Link: connectionMode: PAYMENT_LINK tạo ra một URL có thể chia sẻ mà không yêu cầu các URL chuyển hướng.

Điểm cuối (Endpoints)

Thử nghiệm	Sẽ được cung cấp
Sản xuất	Lấy từ trang API Keys trong Dashboard của người bán

Chữ ký (Signature)

Tất cả các yêu cầu và phản hồi đều được ký bằng RSA với MD5 để đảm bảo tính toàn vẹn và xác thực.

Tạo chữ ký (Người bán -> GLODIPAY)

Ký các payload yêu cầu bằng khóa riêng của người bán (lấy từ Dashboard người bán).

Các bước:

• Thu thập tất cả các tham số yêu cầu ngoại trừ signature dưới dạng đối tượng khóa-giá trị phẳng.
• Sắp xếp các khóa theo thứ tự tăng dần tự nhiên (SORT_NATURAL / localeCompare với numeric: true).
• Cắt bỏ khoảng trắng khỏi tất cả các giá trị chuỗi (đệ quy).
• Tuần tự hóa thành chuỗi JSON.
• Ký bằng openssl_sign(..., 'md5WithRSAEncryption').
• Mã hóa Base64 đầu ra nhị phân.

Xác minh chữ ký (GLODIPAY -> Người bán)

Xác minh các phản hồi và webhook của GLODIPAY bằng khóa công khai của GLODIPAY (có sẵn trong Cổng thông tin).

Các bước:

• Tách signature khỏi payload.
• Sắp xếp các khóa còn lại theo thứ tự tăng dần tự nhiên.
• Cắt bỏ khoảng trắng khỏi tất cả các giá trị chuỗi (đệ quy).
• Tuần tự hóa thành chuỗi JSON.
• Xác minh bằng openssl_verify(..., base64_decode($signature), $publicKey, 'md5WithRSAEncryption').
• Giá trị trả về 1 = hợp lệ.

Lưu ý (Node.js): Chuyển đổi tất cả các giá trị số thành chuỗi trước khi sắp xếp/tuần tự hóa. Thoát các dấu gạch chéo xuôi trong chuỗi JSON: .replace(///g, '\/').

Thông số kỹ thuật API

POST PAYMENT (Checkout V2)

Tạo một phiên thanh toán và nhận URL trang thanh toán được lưu trữ. Trang được lưu trữ sẽ tự động hiển thị tất cả các phương thức thanh toán có sẵn cho người mua.

Endpoint: POST /v2/checkout Phương thức: Form Post Content-Type: application/x-www-form-urlencoded (Form Data)

Tham số yêu cầu (Request Parameters)

merchantId	String(1,50)	M	ID của người bán
orderRef	String(1,250)	M	Mã tham chiếu giao dịch duy nhất cho mỗi người bán
amount	Float	M	Số tiền hóa đơn. Tối thiểu/tối đa được cấu hình cho mỗi người bán
currency	String(3)	M	Mã tiền tệ ISO 4217. Ví dụ: USD
cancelUrl	String(1,300)	M	(Frontend) URL để chuyển hướng người mua khi hủy bỏ. Phải là https.
callbackUrl	String(1,300)	M	(Frontend) URL để chuyển hướng người mua sau khi thanh toán thành công. Phải là https.
notificationUrl	String(1,300)	M	Endpoint máy chủ của bạn để nhận webhook (IPN). Phải là https.
errorUrl	String(1,300)	M	(Frontend) URL để chuyển hướng người mua khi có lỗi. Phải là https.
orderDescription	String(max:3000)	M	Mô tả ngắn gọn hiển thị trên màn hình thanh toán
metadata	JSON	O	Các cặp khóa-giá trị được gắn vào phiên. Được trả về trong IPN và phản hồi truy vấn
transactionDocuments	JSON	O	Tài liệu hỗ trợ cho giao dịch
paymentMethod	String	M	(Các) phương thức thanh toán sẽ hiển thị. Xem các giá trị paymentMethod
paymentFilter	JSON	O	Các loại phương thức thanh toán cần loại trừ khỏi phiên
paymentSorter	JSON	O	Mảng có thứ tự các loại phương thức thanh toán để kiểm soát thứ tự hiển thị. Các giá trị hợp lệ: card, paypal, ibanking_push, local_bank_transfer, wire_transfer, wallet, skrill, alipay, wechat, googlepay, applepay, crypto, apm
feeBySeller	Number(0-100)	O	Phần trăm phí xử lý do người bán trả. 0 = người mua trả 100%. Tối đa 2 chữ số thập phân
billingFirstName	String(max:255)	O	Tên thanh toán
billingLastName	String(max:255)	O	Họ thanh toán
billingStreet1	String(max:255)	O	Địa chỉ đường phố dòng 1
billingStreet2	String(max:255)	O	Địa chỉ đường phố dòng 2
billingCity	String(max:255)	O	Thành phố
billingEmail	String(max:255)	O	Địa chỉ email người mua
billingState	String(2,255)	O	Bang / Tỉnh
billingCountry	String	O	Mã quốc gia ISO 3166-1 alpha-2
billingPostalCode	String(max:25)	O	Mã bưu điện / ZIP
billingPhoneCountryCode	String(max:10)	O	Mã vùng quốc gia của điện thoại. Ví dụ: 1 cho Mỹ, 91 cho Ấn Độ
billingPhoneNumber	String(max:20)	O	Số điện thoại
brandName	String(1,255)	O	Ghi đè tên thương hiệu hiển thị trên màn hình thanh toán được lưu trữ
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 hiển thị trên màn hình thanh toán được lưu trữ
customerIp	String	O	Địa chỉ IP của khách hàng
websiteUrl	String(max:300)	O	URL trang web của người bán
signature	String(max:750)	M	Chữ ký RSA-MD5. Xem phần Chữ ký
connectionMode	String	O	DIRECT_POST hoặc API
expiresAt	String	O	Thời gian hết hạn phiên ở định dạng ISO 8601 kèm micro giây. Ví dụ: 2025-09-14T14:03:42.102862Z. Mặc định: 24 giờ

M = Bắt buộc, O = Tùy chọn

paymentMethod

Chỉ định phương thức thanh toán nào sẽ hiển thị trên trang thanh toán được lưu trữ.

ALL	Tất cả các phương thức thanh toán có sẵn
APM	Tất cả các phương thức thanh toán ngoại trừ thẻ
card	Thẻ tín dụng / Thẻ ghi nợ
googlepay	Google Pay
applepay	Apple Pay
paypal	PayPal
ibanking_push	Chuyển khoản ngân hàng trực tuyến tức thì
local_bank_transfer	Chuyển tiền qua ngân hàng trong nước
wire_transfer	Chuyển tiền điện tử trực tiếp
wallet	Ví điện tử
alipay	Alipay
wechat	WeChat Pay
skrill	Skrill
crypto	Tiền điện tử

paymentFilter

Mảng JSON gồm các giá trị loại phương thức thanh toán để loại trừ khỏi phiên.

["googlepay", "applepay"]

Ví dụ yêu cầu

{
  "merchantId": "1100000123",
  "orderRef": "ORDER-001",
  "amount": 100.00,
  "currency": "USD",
  "paymentMethod": "card",
  "callbackUrl": "https://yoursite.com/callback",
  "notificationUrl": "https://yoursite.com/webhook",
  "cancelUrl": "https://yoursite.com/cancel",
  "errorUrl": "https://yoursite.com/error",
  "orderDescription": "Test order",
  "billingFirstName": "John",
  "billingLastName": "Doe",
  "billingStreet1": "123 Main St",
  "billingStreet2": "",
  "billingCity": "New York",
  "billingEmail": "john@example.com",
  "billingState": "NY",
  "billingCountry": "US",
  "billingPostalCode": "10001",
  "billingPhoneCountryCode": "1",
  "billingPhoneNumber": "5551234567",
  "brandName": " Client Form Simulate",
  "colorMode": " rgba(224,230,5,1)---rgba(166,233,15,1)---rgba(105,193,28,1)",
  "logoSource": "",
  "customerIp": "1.2.3.4",
  "connectionMode": "API",
  "signature": "base64-encoded-signature"
}

Phản hồi -- connectionMode: API

Phương thức: POST Content-Type: application/json

status	String	created
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 trên trang thanh toán được lưu trữ
message	String	Thông báo dễ hiểu cho người dùng

Trang thanh toán được lưu trữ tại paymentLink tự động hiển thị tất cả các phương thức thanh toán có sẵn (bộ sưu tập đa PSP) cho người mua. Trang này xử lý việc chọn phương thức, hiển thị phí và chuyển hướng đến PSP.

Ví dụ -- Thành công:

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

Ví dụ -- Lỗi:

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

Phản hồi -- connectionMode: DIRECT_POST

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

Dữ liệu gửi đến callbackUrl

Sau khi thanh toán, GLODIPAY chuyển hướng người mua đến callbackUrl qua GET với tham số truy vấn payload:

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

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

status	String	Trạng thái giao dịch cuối cùng. Xem phần 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

SERVER TO SERVER -- S2S Card V2

Gửi chi tiết thẻ trực tiếp từ máy chủ của bạn, bỏ qua trang thanh toán được lưu trữ. Hỗ trợ tự động chuyển tầng qua nhiều PSP.

Endpoint: POST /v2/card/api Phương thức: POST Content-Type: application/json

Tham số yêu cầu (Request Parameters)

Bao gồm tất cả các tham số từ POST PAYMENT (Checkout V2), cộng với các trường thẻ và thông tin thanh toán sau:

billingFirstName	String(max:255)	M	Tên thanh toán
billingLastName	String(max:255)	M	Họ thanh toán
billingStreet1	String(max:255)	M	Địa chỉ đường phố dòng 1
billingStreet2	String(max:255)	O	Địa chỉ đường phố dòng 2
billingCity	String(max:255)	M	Thành phố
billingEmail	String(max:255)	M	Địa chỉ email người mua
billingState	String(min:2, max:255)	C	Bang / Tỉnh. Bắt buộc khi billingCountry là US hoặc CA
billingCountry	String	M	Mã quốc gia ISO 3166-1 alpha-2
billingPostalCode	String(max:25)	M	Mã bưu điện / ZIP
billingPhoneCountryCode	String(max:10)	O	Mã vùng quốc gia của điện thoại. Ví dụ: 1 cho Mỹ, 91 cho Ấn Độ
billingPhoneNumber	String(max:30)	M	Số điện thoại
cardNumber	String(12,19)	M	Số thẻ. Ví dụ: 4111111111111111
cardMonth	String	M	Tháng hết hạn. Ví dụ: 12
cardYear	String	M	Năm hết hạn (2 chữ số). Ví dụ: 30
cardSecurityCode	String(3,4)	M	CVV / CVC
customerIp	String	M	Địa chỉ IP của khách hàng
browserDetails	JSON	C	Dấu vân tay trình duyệt. Xem Đối tượng browserDetails

M = Bắt buộc, O = Tùy chọn, C = Có điều kiện

Đối tượng browserDetails

Bắt buộc với mọi request S2S card. Có thể gửi dưới dạng đối tượng JSON (lồng nhau) hoặc chuỗi được mã hóa JSON. Khóa viết snake_case như bảng dưới; gửi camelCase vẫn được, hệ thống tự chuẩn hóa.

accept_header	String	M	Browser Accept header. Ví dụ: text/html,application/xhtml+xml
screen_width	String	M	Chiều rộng màn hình tính bằng pixel. Ví dụ: 1920
screen_height	String	M	Chiều cao màn hình tính bằng pixel. Ví dụ: 1080
screen_color_depth	String	M	Độ sâu màu màn hình tính bằng bit. Ví dụ: 24
window_width	String	M	Chiều rộng Viewport tính bằng pixel. Ví dụ: 1440
window_height	String	M	Chiều cao Viewport tính bằng pixel. Ví dụ: 900
language	String	M	Ngôn ngữ trình duyệt. Ví dụ: en-US
java_enabled	String	M	Liệu Java có được bật không. "true" hoặc "false"
user_agent	String	M	Chuỗi User Agent của trình duyệt
time_zone	String	M	Độ lệch múi giờ theo giờ so với UTC. Ví dụ: 7 cho UTC+7
time_zone_name	String	M	Tên múi giờ IANA. Ví dụ: Asia/Ho_Chi_Minh

Ví dụ thân bài yêu cầu (Request body):

{
  "merchantId": "1100000123",
  "orderRef": "ORDER-001",
  "amount": "100.00",
  "currency": "USD",
  "paymentMethod": "card",
  "callbackUrl": "https://yoursite.com/callback",
  "notificationUrl": "https://yoursite.com/webhook",
  "cancelUrl": "https://yoursite.com/cancel",
  "errorUrl": "https://yoursite.com/error",
  "orderDescription": "Test order",
  "billingFirstName": "John",
  "billingLastName": "Doe",
  "billingStreet1": "123 Main St",
  "billingStreet2": "",
  "billingCity": "New York",
  "billingEmail": "john@example.com",
  "billingState": "NY",
  "billingCountry": "US",
  "billingPostalCode": "10001",
  "billingPhoneCountryCode": "1",
  "billingPhoneNumber": "5551234567",
  "cardNumber": "4111111111111111",
  "cardMonth": "12",
  "cardYear": "30",
  "cardSecurityCode": "123",
  "customerIp": "1.2.3.4",
  "browserDetails": {
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
    "screen_width": "1920",
    "screen_height": "1080",
    "screen_color_depth": "24",
    "window_width": "1440",
    "window_height": "900",
    "language": "en-US",
    "java_enabled": "false",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "time_zone": "7",
    "time_zone_name": "Asia/Ho_Chi_Minh"
  },
  "signature": "base64-encoded-signature"
}

Đoạn mã JavaScript để thu thập browserDetails:

document.addEventListener('DOMContentLoaded', () => {
  const browserDetails = {
    accept_header: "{{ request()->header('Accept', 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8') }}",
    screen_width: window.screen.width.toString(),
    screen_height: window.screen.height.toString(),
    screen_color_depth: window.screen.colorDepth.toString(),
    window_width: String(window.innerWidth || document.documentElement.clientWidth || screen.width),
    window_height: String(window.innerHeight || document.documentElement.clientHeight || screen.height),
    language: navigator.language,
    java_enabled: 'false',
    user_agent: navigator.userAgent,
    time_zone: String(-new Date().getTimezoneOffset() / 60),
    time_zone_name: Intl.DateTimeFormat().resolvedOptions().timeZone
  };

  document.getElementById('browserDetails').value = JSON.stringify(browserDetails, null, 2);
});

Phản hồi (Response)

Content-Type: application/json

Giao dịch hoàn tất (không yêu cầu 3DS):

{
  "status": " created",
  "data": {
    "transactionId": "01jwz0ty1640apxvmyzqpvc18a",
  },
  "message": "The transaction has been successfully completed."
}

Yêu cầu xác thực 3DS:

{
  "status": "redirect",
  "data": {
    "transactionId": "01jwz0ty1640apxvmyzqpvc18a",
    "url": "https://payment.gpayprocessing.com/card/3ds/01jwz0ty1640apxvmyzqpvc18a"
  },
  "message": "Please redirect the user to complete the payment."
}

Chuyển hướng người mua đến url để hoàn tất 3DS. Sau khi xác minh, GLODIPAY xử lý giao dịch và gửi kết quả qua IPN đến notificationUrl và chuyển hướng người mua đến callbackUrl.

Đang chờ xử lý (Pending):

{
  "status": "pending",
  "data": {
    "transactionId": "01jwz0ty1640apxvmyzqpvc18a",
  },
  "message": "pending"
}

Lỗi xác thực (HTTP 422):

{
  "status": "error",
  "message": "Invalid request data.",
  "errors": [
    {
      "field": "billingEmail",
      "message": ["The billing email field is required."]
    },
    {
      "field": "customerIp",
      "message": ["The customer ip field is required."]
    }
  ]
}

Lỗi (HTTP 400/500):

{
  "status": "error",
  "data": {
    "transactionId": "01jwz0ty1640apxvmyzqpvc18a",
  },
  "message": "No payment provider could process this transaction. Please try again or contact support."
}

Tự động chuyển tầng (Auto-Cascade): Khi is_auto_cascade được bật cho người bán, v2 sẽ tự động thử lại việc tính phí thẻ trên tất cả các PSP đang hoạt động theo thứ tự ưu tiên trước khi trả về phản hồi cuối cùng. Các thất bại của từng PSP riêng lẻ sẽ được ẩn đi trong quá trình chuyển tầng -- chỉ kết quả cuối cùng mới được trả về và gửi qua IPN.

CARD IFRAME V2

Tạo phiên iframe cho thẻ. Thay vì gửi chi tiết thẻ server-to-server, GLODIPAY trả về một URL đã ký cho trang nhập thẻ được lưu trữ (iframe) mà người bán nhúng vào hoặc chuyển hướng đến. Dữ liệu thẻ được nhập trực tiếp trên trang do GLODIPAY lưu trữ -- phạm vi PCI vẫn thuộc về GLODIPAY.

Endpoint: POST /v2/card/iframe Phương thức: POST Content-Type: application/x-www-form-urlencoded (Form Data)

Tham số yêu cầu (Request Parameters)

Giống như POST PAYMENT (Checkout V2). Không có trường thẻ nào được gửi -- người mua nhập chi tiết thẻ trên trang iframe được lưu trữ.

Phản hồi (Response)

Luôn trả về JSON.

status	String	created
transactionId	String (ULID)	ID giao dịch của GLODIPAY
url	String	URL đã ký -- nhúng URL này vào iframe hoặc chuyển hướng người mua để hoàn tất việc nhập thẻ
message	String	Thông báo dễ hiểu cho người dùng

Ví dụ -- Thành công:

{
  "status": "created",
  "transactionId": "01jza90dy6w82dfrrqvadn5vs4",
  "url": "https://payment.gpayprocessing.com/v2/card-iframe/01jza90dy6w82dfrrqvadn5vs4?...",
  "message": "Iframe card created successfully"
}

Ví dụ -- Lỗi:

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

Sau khi người mua gửi chi tiết thẻ trên trang được lưu trữ, kết quả giao dịch sẽ được gửi qua IPN đến notificationUrl và người mua được chuyển hướng đến callbackUrl hoặc errorUrl.

TRANSACTION QUERY (Truy vấn giao dịch)

Truy vấn trạng thái hiện tại và chi tiết đầy đủ của một giao dịch.

Endpoint: POST /v2/checkout/query Phương thức: POST Content-Type: application/json

Yêu cầu (Request)

transactionId	String (ULID)	M	ID giao dịch của GLODIPAY
signature	String(max:750)	M	Chữ ký RSA-MD5

Phản hồi (Response)

Trả về cùng một payload như webhook NOTIFICATION.

NOTIFICATION (Transaction IPN)

GLODIPAY gửi một HTTP POST đến notificationUrl của bạn khi một giao dịch đạt đến trạng thái cuối cùng.

Phương thức: POST Content-Type: application/json

Chính sách gửi lại (Retry policy): GLODIPAY có thể gửi lại IPN cho các giao dịch chưa được xác nhận. Máy chủ của bạn nên trả về {"returnCode":"100"} ngay khi nhận được thông báo. Nếu endpoint của bạn không khả dụng hoặc trả về phản hồi không mong đợi, GLODIPAY sẽ cố gắng gửi lại IPN.

Payload

merchantId	String	M	ID của người bán
transactionId	String	M	ID giao dịch của GLODIPAY (ULID)
transactionNumber	String	M	Số giao dịch dễ hiểu của GLODIPAY
ref	String	M	orderRef của người bán
currency	String	M	Mã tiền tệ ISO 4217
amount	Float	M	Số tiền hóa đơn
paidAmount	Float	O	Số tiền thực tế thu từ người mua (bao gồm cả phí người mua)
settlementAmount	Float	O	Số tiền được thanh quyết toán cho người bán
estimationSettlementAt	ISO 8601 datetime	O	Thời gian thanh quyết toán dự kiến. Ví dụ: 2023-12-16T02:13:37+00:00
fees	JSON	O	Phân tách phí. Xem đối tượng fees
paymentMethodDetails	JSON	O	Phương thức thanh toán đã dùng. Xem đối tượng paymentMethodDetails
status	String	M	Trạng thái giao dịch. Xem phần Giá trị trạng thái
statusCode	Number	M	Mã trạng thái số. Xem phần Mã trạng thái
metadata	JSON	O	Các cặp khóa-giá trị từ phiên thanh toán ban đầu
transactionDocuments	JSON	O	Tài liệu hỗ trợ từ phiên thanh toán ban đầu
message	String	O	Thông báo trạng thái dễ hiểu
descriptor	String	O	Mô tả giao dịch (descriptor)
transactionCreatedAt	ISO 8601 datetime	M	Thời gian tạo giao dịch trong hệ thống GLODIPAY
originalTransactionCreatedAt	ISO 8601 datetime	M	Thời gian tạo giao dịch tại PSP
signature	String	M	Chữ ký RSA-MD5 -- xác minh bằng khóa công khai của GLODIPAY

đối tượng fees

buyer	Float	Số phí người mua phải trả
seller	Float	Số phí người bán phải trả
rolling	Float	Số tiền ký quỹ (rolling reserve)
operate	Float	Tổng phí vận hành (processor + GLODIPAY + đối tác)
estimationRollingReleaseAt	ISO 8601 datetime	Thời gian dự kiến giải tỏa tiền ký quỹ

đối tượng paymentMethodDetails

displayName	String	Nhãn phương thức thanh toán
group	String	Loại nhóm phương thức thanh toán
family	String	Loại họ phương thức thanh toán
type	String	Loại phương thức thanh toán. Có thể dùng trong các trường paymentMethod / paymentFilter

Ví dụ Payload IPN:

{
  "merchantId": "1100000123",
  "transactionId": "01jza90dy6w82dfrrqvadn5vs4",
  "transactionNumber": "2604-1713100800",
  "ref": "ORDER-001",
  "currency": "USD",
  "amount": 100.00,
  "paidAmount": 105.00,
  "settlementAmount": 95.00,
  "estimationSettlementAt": "2026-04-16T00:00:00+00:00",
  "fees": {
    "buyer": 5.00,
    "seller": 5.00,
    "rolling": 2.00,
    "operate": 3.00,
    "estimationRollingReleaseAt": "2026-05-14T00:00:00+00:00"
  },
  "status": "successful",
  "statusCode": 6,
  "paymentMethodDetails": {
    "displayName": "Credit / Debit Card",
    "group": "card",
    "family": "card",
    "type": "card"
  },
  "metadata": { "orderId": "12345" },
  "transactionCreatedAt": "2026-04-14T10:00:00+00:00",
  "originalTransactionCreatedAt": "2026-04-14T10:00:01+00:00",
  "signature": "base64-encoded-rsa-signature"
}

Phản hồi (Người bán -> GLODIPAY)

Máy chủ của bạn phải phản hồi trong vòng 30 giây:

{
  "returnCode": "100",
  "description": "Received"
}

returnCode	String	R	Phải là "100" để xác nhận đã nhận
description	String(1,1500)	O	Mô tả tùy chọn

REFUND API (API Hoàn tiền)

Khởi tạo hoàn tiền cho một giao dịch đã hoàn tất.

Endpoint: POST /v2/refund Phương thức: POST Content-Type: application/json

Yêu cầu (Request)

transactionId	String (ULID)	M	ID giao dịch nhận được từ IPN thanh toán
amount	Float	M	Số tiền hoàn lại. Tối thiểu: 0.10 (hoặc toàn bộ số tiền đối với một số nhà cung cấp). Tối đa: số tiền còn lại có thể hoàn trả (paidAmount − đã hoàn tiền)
reason	String(max:1000)	O	Mô tả ngắn gọn lý do hoàn tiền
signature	String(max:750)	M	Chữ ký RSA-MD5

Lưu ý: Một số nhà cung cấp nhất định (ví dụ: PayAgency, SmartPay, ClisaPay, FinvyPay, WPay) chỉ hỗ trợ hoàn tiền toàn bộ số tiền. Hệ thống sẽ thực thi số tiền hoàn lại tối thiểu tương ứng.

Phản hồi (Response)

Content-Type: application/json

Hoàn tiền đã được tạo và xử lý ngay lập tức (đã bật tự động hoàn tiền):

{
  "status": "success",
  "message": null,
  "data": {
    "refundId": "01jzabk09xc4pbgwe8hyg4cwbf",
    "refundNumber": "2507-1751420414"
  }
}

Hoàn tiền đã được tạo và đang chờ phê duyệt thủ công:

{
  "status": "success",
  "message": "Refund created and waiting for approval.",
  "data": {
    "refundId": "01jzabk09xc4pbgwe8hyg4cwbf",
    "refundNumber": "2507-1751420414"
  }
}

Lỗi xác thực (HTTP 422):

{
  "status": "error",
  "message": "Invalid request data.",
  "errors": [
    {
      "field": "amount",
      "message": ["The amount must be between 0.1 and 100."]
    }
  ]
}

REFUND QUERY (Truy vấn hoàn tiền)

Truy vấn trạng thái mới nhất của một giao dịch hoàn tiền.

Endpoint: POST /v2/refund/query Phương thức: POST Content-Type: application/json

Yêu cầu (Request)

refundId	String (ULID)	M	ID hoàn tiền của GLODIPAY (từ phản hồi Refund API hoặc Refund IPN)
signature	String(max:750)	M	Chữ ký RSA-MD5

Phản hồi (Response)

Content-Type: application/json

status	String	success
message	String	Thông báo dễ hiểu cho người dùng
data	JSON	Chi tiết hoàn tiền. Giống các trường trong payload REFUND NOTIFICATION

Ví dụ:

{
  "status": "success",
  "message": "",
  "data": {
    "transactionId": "01jza90dy6w82dfrrqvadn5vs4",
    "ref": "ORDER-001",
    "refundId": "01jzabk09xc4pbgwe8hyg4cwbf",
    "currency": "USD",
    "refundAmount": 50.00,
    "status": "refund_successful",
    "statusCode": 11,
    "reason": "Customer request",
    "originalRefundCreatedAt": "2026-04-14T11:00:00+00:00",
    "refundCreatedAt": "2026-04-14T11:00:01+00:00",
    "transactionCreatedAt": "2026-04-14T10:00:00+00:00",
    "signature": "base64-encoded-rsa-signature"
  }
}

REFUND NOTIFICATION (Refund IPN)

GLODIPAY gửi một HTTP POST đến notificationUrl của bạn khi trạng thái hoàn tiền thay đổi.

Phương thức: POST Content-Type: application/json

Payload

transactionId	String	M	ID giao dịch gốc của GLODIPAY
ref	String	M	orderRef của người bán
refundId	String	M	ID hoàn tiền của GLODIPAY
currency	String	M	Mã tiền tệ ISO 4217
refundAmount	Float	M	Số tiền hoàn lại
status	String	M	Trạng thái hoàn tiền. Xem phần Giá trị trạng thái
statusCode	Number	M	Mã trạng thái số. Xem phần Mã trạng thái
metadata	JSON	O	Các cặp khóa-giá trị từ phiên thanh toán ban đầu
reason	String	O	Lý do hoàn tiền
message	String	O	Thông báo trạng thái dễ hiểu
originalRefundCreatedAt	ISO 8601 datetime	M	Thời gian tạo hoàn tiền tại PSP
refundCreatedAt	ISO 8601 datetime	M	Thời gian tạo hoàn tiền trong hệ thống GLODIPAY
transactionCreatedAt	ISO 8601 datetime	M	Thời gian tạo giao dịch gốc
signature	String	M	Chữ ký RSA-MD5 -- xác minh bằng khóa công khai của GLODIPAY

Phản hồi (Người bán -> GLODIPAY)

{
  "returnCode": "100",
  "description": "Received"
}

Mô phỏng thanh toán (Thẻ thử nghiệm)

Sử dụng môi trường Thử nghiệm (Test). Không có chi phí thực tế nào được tính.

Không có 3DS	4111 1111 1111 1111	01/30	029	—
Không có 3DS	5555 5555 5555 4444	01/30	029	—
Thanh toán 3DS	4012 8888 8888 1881	01/30	029	Thành công: 123456 / Thất bại: 111111
Thanh toán 3DS	5111 1111 1111 1118	01/30	029	Thành công: 123456 / Thất bại: 111111
Thanh toán 3DS	4141 4141 4141 4141	12/30	123	Thành công: 123456 / Thất bại: 111111

Phụ lục

Phương thức thanh toán (Payment Methods)

card	Thẻ tín dụng hoặc thẻ ghi nợ
googlepay	Google Pay
applepay	Apple Pay
paypal	PayPal
ibanking_push	Chuyển khoản ngân hàng trực tuyến tức thì
local_bank_transfer	Chuyển tiền qua ngân hàng trong nước
wire_transfer	Chuyển tiền điện tử trực tiếp
wallet	Ví điện tử
alipay	Alipay
wechat	WeChat Pay
skrill	Skrill
crypto	Tiền điện tử
APM	Tất cả phương thức trừ thẻ
ALL	Tất cả phương thức có sẵn

Chế độ kết nối (Connection Modes)

DIRECT_POST	(Mặc định) Trình duyệt được chuyển hướng đến trang thanh toán ngay lập tức.
API	Trả về URL paymentLink trong phản hồi JSON.

Giá trị trạng thái (Status Values)

Giá trị chuỗi được trả về trong trường status của payload IPN và phản hồi truy vấn.

incomplete	Giao dịch đã khởi tạo, đang chờ hành động
pending	Đang chờ xác nhận thanh toán
under_review	Giao dịch đang được xem xét
successful	Thanh toán hoàn tất thành công
failed	Thanh toán thất bại
error	Đã xảy ra lỗi hệ thống
canceled	Giao dịch đã bị hủy
rejected	Giao dịch bị từ chối
expired	Giao dịch hết hạn
released	Tiền đã giải tỏa / thanh quyết toán
documents_uploaded	Tài liệu hỗ trợ đã tải lên
refund_initiated	Yêu cầu hoàn tiền đã khởi tạo
refund_under_review	Hoàn tiền đang xem xét
refund_successful	Hoàn tiền thành công
refund_failed	Hoàn tiền thất bại
refund_partially_successful	Hoàn tiền một phần thành công
refund_partially_failed	Hoàn tiền một phần thất bại
void_initiated	Void đã khởi tạo
void_under_review	Void đang xem xét
void_successful	Void thành công
void_failed	Void thất bại
void_partially_successful	Void một phần thành công
void_partially_failed	Void một phần thất bại
chargeback_alert	Nhận được cảnh báo chargeback
chargebacked	Giao dịch đã bị chargeback
dispute	Tranh chấp đã được mở

Mã trạng thái (Status Codes)

Mã số trong trường statusCode của payload IPN và phản hồi truy vấn.

1	incomplete	Giao dịch đã khởi tạo
2	pending	Đang chờ xác nhận
3	error	Lỗi hệ thống
4	failed	Thanh toán thất bại
5	under_review	Đang xem xét
6	successful	Thanh toán thành công
7	released	Đã giải tỏa / thanh quyết toán
8	refund_initiated	Hoàn tiền đã khởi tạo
9	refund_failed	Hoàn tiền thất bại
10	refund_under_review	Hoàn tiền đang xem xét
11	refund_successful	Hoàn tiền thành công
12	refund_partially_failed	Hoàn tiền một phần thất bại
13	refund_partially_successful	Hoàn tiền một phần thành công
14	canceled	Đã hủy
15	rejected	Bị từ chối
16	expired	Hết hạn
17	documents_uploaded	Tài liệu đã tải lên
18	void_initiated	Void đã khởi tạo
19	void_under_review	Void đang xem xét
20	void_successful	Void thành công
21	void_failed	Void thất bại
22	void_partially_successful	Void một phần thành công
23	void_partially_failed	Void một phần thất bại
24	chargeback_alert	Cảnh báo chargeback
25	chargebacked	Đã bị chargeback
26	dispute	Tranh chấp đã mở

Mã tiền tệ (Currency Codes)

GLODIPAY tuân theo tiêu chuẩn ISO 4217.

• Checkout API (/v2/checkout) và iFrame API (/v2/card/iframe): chỉ chấp nhận USD.
• Server-to-Server Card API (/v2/card/api): tiền tệ được chấp nhận tùy thuộc vào nhà cung cấp thanh toán. Các giá trị phổ biến được hỗ trợ:

USD	Đô la Mỹ
EUR	Euro
GBP	Bảng Anh
AUD	Đô la Úc
AED	UAE Dirham
VND	Việt Nam Đồng

Mã quốc gia (Country Codes)

GLODIPAY sử dụng mã hai chữ cái ISO 3166-1 alpha-2 cho trường billingCountry.

AD	Andorra
AE	United Arab Emirates
AF	Afghanistan
AG	Antigua and Barbuda
AI	Anguilla
AL	Albania
AM	Armenia
AO	Angola
AQ	Antarctica
AR	Argentina
AS	American Samoa
AT	Austria
AU	Australia
AW	Aruba
AX	Åland Islands
AZ	Azerbaijan
BA	Bosnia and Herzegovina
BB	Barbados
BD	Bangladesh
BE	Belgium
BF	Burkina Faso
BG	Bulgaria
BH	Bahrain
BI	Burundi
BJ	Benin
BL	Saint Barthélemy
BM	Bermuda
BN	Brunei Darussalam
BO	Bolivia, Plurinational State of
BQ	Bonaire, Sint Eustatius and Saba
BR	Brazil
BS	Bahamas
BT	Bhutan
BV	Bouvet Island
BW	Botswana
BY	Belarus
BZ	Belize
CA	Canada
CC	Cocos (Keeling) Islands
CD	Congo, Democratic Republic of the
CF	Central African Republic
CG	Congo
CH	Switzerland
CI	Côte d'Ivoire
CK	Cook Islands
CL	Chile
CM	Cameroon
CN	Trung Quốc
CO	Colombia
CR	Costa Rica
CU	Cuba
CV	Cabo Verde
CW	Curaçao
CX	Christmas Island
CY	Cyprus
CZ	Czechia
DE	Đức
DJ	Djibouti
DK	Đan Mạch
DM	Dominica
DO	Dominican Republic
DZ	Algeria
EC	Ecuador
EE	Estonia
EG	Ai Cập
EH	Western Sahara
ER	Eritrea
ES	Tây Ban Nha
ET	Ethiopia
FI	Phần Lan
FJ	Fiji
FK	Falkland Islands (Malvinas)
FM	Micronesia, Federated States of
FO	Faroe Islands
FR	Pháp
GA	Gabon
GB	Vương quốc Anh
GD	Grenada
GE	Georgia
GF	French Guiana
GG	Guernsey
GH	Ghana
GI	Gibraltar
GL	Greenland
GM	Gambia
GN	Guinea
GP	Guadeloupe
GQ	Equatorial Guinea
GR	Hy Lạp
GS	South Georgia and the South Sandwich Islands
GT	Guatemala
GU	Guam
GW	Guinea-Bissau
GY	Guyana
HK	Hồng Kông
HM	Heard Island and McDonald Islands
HN	Honduras
HR	Croatia
HT	Haiti
HU	Hungary
ID	Indonesia
IE	Ireland
IL	Israel
IM	Isle of Man
IN	Ấn Độ
IO	British Indian Ocean Territory
IQ	Iraq
IR	Iran, Islamic Republic of
IS	Iceland
IT	Ý
JE	Jersey
JM	Jamaica
JO	Jordan
JP	Nhật Bản
KE	Kenya
KG	Kyrgyzstan
KH	Campuchia
KI	Kiribati
KM	Comoros
KN	Saint Kitts and Nevis
KP	Triều Tiên
KR	Hàn Quốc
KW	Kuwait
KY	Cayman Islands
KZ	Kazakhstan
LA	Lào
LB	Lebanon
LC	Saint Lucia
LI	Liechtenstein
LK	Sri Lanka
LR	Liberia
LS	Lesotho
LT	Lithuania
LU	Luxembourg
LV	Latvia
LY	Libya
MA	Ma-rốc
MC	Monaco
MD	Moldova
ME	Montenegro
MF	Saint Martin (phần thuộc Pháp)
MG	Madagascar
MH	Marshall Islands
MK	Bắc Macedonia
ML	Mali
MM	Myanmar
MN	Mông Cổ
MO	Ma Cao
MP	Northern Mariana Islands
MQ	Martinique
MR	Mauritania
MS	Montserrat
MT	Malta
MU	Mauritius
MV	Maldives
MW	Malawi
MX	Mexico
MY	Malaysia
MZ	Mozambique
NA	Namibia
NC	New Caledonia
NE	Niger
NF	Norfolk Island
NG	Nigeria
NI	Nicaragua
NL	Hà Lan
NO	Na Uy
NP	Nepal
NR	Nauru
NU	Niue
NZ	New Zealand
OM	Oman
PA	Panama
PE	Peru
PF	French Polynesia
PG	Papua New Guinea
PH	Philippines
PK	Pakistan
PL	Ba Lan
PM	Saint Pierre and Miquelon
PN	Pitcairn
PR	Puerto Rico
PS	Palestine
PT	Bồ Đào Nha
PW	Palau
PY	Paraguay
QA	Qatar
RE	Réunion
RO	Romania
RS	Serbia
RU	Nga
RW	Rwanda
SA	Ả Rập Xê-út
SB	Solomon Islands
SC	Seychelles
SD	Sudan
SE	Thụy Điển
SG	Singapore
SH	Saint Helena, Ascension and Tristan da Cunha
SI	Slovenia
SJ	Svalbard and Jan Mayen
SK	Slovakia
SL	Sierra Leone
SM	San Marino
SN	Senegal
SO	Somalia
SR	Suriname
SS	Nam Sudan
ST	Sao Tome and Principe
SV	El Salvador
SX	Sint Maarten (phần thuộc Hà Lan)
SY	Syria
SZ	Eswatini
TC	Turks and Caicos Islands
TD	Chad
TF	French Southern Territories
TG	Togo
TH	Thái Lan
TJ	Tajikistan
TK	Tokelau
TL	Timor-Leste
TM	Turkmenistan
TN	Tunisia
TO	Tonga
TR	Thổ Nhĩ Kỳ
TT	Trinidad and Tobago
TV	Tuvalu
TW	Đài Loan
TZ	Tanzania
UA	Ukraine
UG	Uganda
UM	United States Minor Outlying Islands
US	Hoa Kỳ
UY	Uruguay
UZ	Uzbekistan
VA	Holy See
VC	Saint Vincent and the Grenadines
VE	Venezuela
VG	Virgin Islands (Anh)
VI	Virgin Islands (Mỹ)
VN	Việt Nam
VU	Vanuatu
WF	Wallis and Futuna
WS	Samoa
YE	Yemen
YT	Mayotte
ZA	Nam Phi
ZM	Zambia
ZW	Zimbabwe

Để xem danh sách ISO 3166 đầy đủ, hãy truy cập https://www.iso.org/iso-3166-country-codes.html

Loại thẻ (Card Types)

1	VISA	visa
2	MASTERCARD	mastercard
3	AMERICAN EXPRESS	amex
4	JCB	jcb
5	MAESTRO	maestro
6	DISCOVER	discover
7	UNION PAY	union-pay
8	DINERS	diners

Ví dụ mã nguồn

PHP

<?php

function generateSignature(array $data): string
{
    $privateKey = openssl_pkey_get_private("-----BEGIN PRIVATE KEY-----
YOUR_PRIVATE_KEY_HERE
-----END PRIVATE KEY-----
");

    ksort($data, SORT_NATURAL);
    array_walk_recursive(
        $data,
        static function (&$field) {
            $field = trim($field);
        }
    );

    openssl_sign(json_encode($data), $signature, $privateKey, 'md5WithRSAEncryption');

    return base64_encode($signature);
}

function verifySignature(array $data): bool
{
    $publicKey = openssl_pkey_get_public("-----BEGIN PUBLIC KEY-----
YOUR_GLODIPAY_PUBLIC_KEY_HERE
-----END PUBLIC KEY-----
");

    $dataWithoutSignature = array_filter($data, static function ($key) {
        return $key !== 'signature';
    }, ARRAY_FILTER_USE_KEY);

    $signature = $data['signature'];

    ksort($dataWithoutSignature, SORT_NATURAL);
    array_walk_recursive(
        $dataWithoutSignature,
        static function (&$field) {
            $field = trim($field);
        }
    );

    $result = openssl_verify(
        json_encode($dataWithoutSignature),
        base64_decode($signature),
        $publicKey,
        'md5WithRSAEncryption'
    );

    return $result === 1;
}

// Ví dụ: tạo một v2 checkout (chế độ API)
$payload = [
    'merchantId'       => '1100000123',
    'orderRef'         => 'ORDER-' . time(),
    'amount'           => '100.00',
    'currency'         => 'USD',
    'paymentMethod'    => 'ALL',
    'callbackUrl'      => 'https://yoursite.com/payment/callback',
    'notificationUrl'  => 'https://yoursite.com/payment/webhook',
    'cancelUrl'        => 'https://yoursite.com/payment/cancel',
    'errorUrl'         => 'https://yoursite.com/payment/error',
    'orderDescription' => 'Test order',
    'customerIp'       => $_SERVER['REMOTE_ADDR'],
    'connectionMode'   => 'API',
];

$payload['signature'] = generateSignature($payload);

$ch = curl_init('https://payment-sandbox.gpayprocessing.com/v2/checkout');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
// Chuyển hướng người mua đến $result['paymentLink']
header('Location: ' . $result['paymentLink']);
exit;

Node.js

// Save as script.mjs and run: node script.mjs
import { createSign, createVerify } from 'crypto';
import https from 'https';
import querystring from 'querystring';

const PRIVATE_KEY = `-----BEGIN PRIVATE KEY-----
YOUR_PRIVATE_KEY_HERE
-----END PRIVATE KEY-----`;

function phpCast(v) {
    if (typeof v === 'number') return String(v);
    if (typeof v === 'boolean') return v ? '1' : '';
    if (typeof v === 'string') return v.trim();
    if (Array.isArray(v)) return v.map(phpCast);
    if (v && typeof v === 'object') return Object.fromEntries(Object.entries(v).map(([k, val]) => [k, phpCast(val)]));
    return v;
}

function generateSignature(data) {
    const sorted = {};
    Object.keys(data)
        .filter(k => k !== 'signature')
        .sort((a, b) => a.localeCompare(b, undefined, { numeric: true, sensitivity: 'base' }))
        .forEach(k => { sorted[k] = data[k]; });

    const canonical = JSON.stringify(phpCast(sorted))
        .replace(/\//g, '\\/')
        .replace(/[\u0080-\uffff]/g, c => '\\u' + c.charCodeAt(0).toString(16).padStart(4, '0'));

    const sign = createSign('md5WithRSAEncryption');
    sign.update(canonical);
    return sign.sign(PRIVATE_KEY, 'base64');
}

function verifySignature(data) {
    const publicKey = `-----BEGIN PUBLIC KEY-----
YOUR_GLODIPAY_PUBLIC_KEY_HERE
-----END PUBLIC KEY-----`;

    const { signature, ...rest } = data;

    const sorted = {};
    Object.keys(rest)
        .sort((a, b) => a.localeCompare(b, undefined, { numeric: true, sensitivity: 'base' }))
        .forEach(k => { sorted[k] = rest[k]; });

    const canonical = JSON.stringify(phpCast(sorted))
        .replace(/\//g, '\\/')
        .replace(/[\u0080-\uffff]/g, c => '\\u' + c.charCodeAt(0).toString(16).padStart(4, '0'));

    const verify = createVerify('md5WithRSAEncryption');
    verify.update(canonical);
    return verify.verify(publicKey, Buffer.from(signature, 'base64'));
}

// Ví dụ: tạo một v2 checkout (chế độ API)
const payload = {
    merchantId: '1100000123',
    orderRef: 'ORDER-' + Date.now(),
    amount: '100.00',
    currency: 'USD',
    paymentMethod: 'ALL',
    callbackUrl: 'https://yoursite.com/payment/callback',
    notificationUrl: 'https://yoursite.com/payment/webhook',
    cancelUrl: 'https://yoursite.com/payment/cancel',
    errorUrl: 'https://yoursite.com/payment/error',
    orderDescription: 'Test order',
    customerIp: '1.2.3.4',
    connectionMode: 'API',
};

payload.signature = generateSignature(payload);

const postData = querystring.stringify(payload);
const options = {
    hostname: 'payment-sandbox.gpayprocessing.com',
    path: '/v2/checkout',
    method: 'POST',
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Content-Length': Buffer.byteLength(postData),
    },
};

const req = https.request(options, (res) => {
    let body = '';
    res.on('data', chunk => body += chunk);
    res.on('end', () => {
        const result = JSON.parse(body);
        console.log('Payment Link:', result.paymentLink);
        // Chuyển hướng người mua: res.writeHead(302, { Location: result.paymentLink });
    });
});

req.on('error', console.error);
req.write(postData);
req.end();