Server-to-Server Card API

Ask AI

Gửi chi tiết thẻ trực tiếp từ máy chủ của bạn để tính phí người mua mà không cần chuyển hướng họ đến trang thanh toán bên ngoài.

Endpoint: POST /v2/card/api Content-Type: application/json

Endpoint này yêu cầu máy chủ của bạn phải tuân thủ chứng chỉ PCI DSS, vì dữ liệu thẻ thô sẽ đi qua hệ thống của bạn.

---

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
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	Mã bảo mật CVV / CVC. Ví dụ: 123
billingFirstName	String(max:255)	M	Tên (First name) thanh toán. Ví dụ: John
billingLastName	String(max:255)	M	Họ (Last name) thanh toán. Ví dụ: Doe
billingEmail	String(max:255)	M	Địa chỉ email người mua. Ví dụ: john.doe@example.com
billingStreet1	String(max:255)	M	Đị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)	M	Thành phố. Ví dụ: New York
billingState	String(2–255)	C	Bang / Tỉnh. Bắt buộc khi billingCountry là US hoặc CA. Ví dụ: NY
billingCountry	String	M	Mã quốc gia ISO 3166-1 alpha-2. Ví dụ: US. Xem Mã quốc gia
billingPostalCode	String(max:25)	M	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:30)	M	Số điện thoại. Ví dụ: 5551234567
customerIp	String	M	Địa chỉ IP của khách hàng. Ví dụ: 203.0.113.42
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
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
browserDetails	JSON	M	Dấu vân tay trình duyệt. Xem Đối tượng browserDetails
signature	String(max:750)	M	Chữ ký RSA-MD5. Xem Chữ ký

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

---

Đố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.

Trường	Loại	Bắt buộc	Mô tả
accept_header	String	M	Browser Accept header
screen_width	String	M	Chiều rộng màn hình tính bằng pixel
screen_height	String	M	Chiều cao màn hình tính bằng pixel
screen_color_depth	String	M	Độ sâu màu màn hình tính bằng bit
window_width	String	M	Chiều rộng Viewport tính bằng pixel
window_height	String	M	Chiều cao Viewport tính bằng pixel
language	String	M	Ngôn ngữ trình duyệt. Ví dụ: en-US
java_enabled	String	M	"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

Đoạn mã JavaScript:

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)

Tất cả các phản hồi từ endpoint này đều được đóng gói bởi gateway:

{ "status": "...", "message": "...", "data": { ... } }

Thành công (không yêu cầu 3DS)

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

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

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

Chuyển hướng người mua đến data.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 xử lý (Pending)

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

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

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

Lỗi xử lý (HTTP 400/500)

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

---

Tự động chuyển tầng (Auto-Cascade)

Khi được bật cho tài khoản người bán, gateway 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.

---

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