Thông báo IPN
GLODIPAY cung cấp kết quả thanh toán theo thời gian thực tới máy chủ của bạn thông qua Thông báo thanh toán tức thì (Instant Payment Notification - IPN) — một yêu cầu HTTP POST tới notificationUrl mà bạn đã cung cấp khi tạo giao dịch.
Phương thức: POST
Content-Type: application/json
Chính sách gửi lại (Retry policy): Nếu máy chủ của bạn không phản hồi với {"returnCode":"100"} trong vòng 30 giây, GLODIPAY sẽ thực hiện gửi lại. Trình xử lý của bạn nên có tính lũy đẳng (idempotent) — cùng một thông báo có thể được gửi nhiều hơn một lần.
Điều gì kích hoạt IPN: Bất kỳ sự chuyển đổi nào sang trạng thái cuối cùng hoặc trạng thái quan trọng: successful, failed, error, refund_successful, refund_failed, void_successful, v.v.
Các trường Payload
| Trường | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
| 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 sẽ đượ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 |
| fees | JSON | O | Phân tách các loại phí. Xem đối tượng fees bên dưới |
| status | String | M | Trạng thái giao dịch. Xem Giá trị trạng thái |
| statusCode | Number | M | Mã trạng thái số. Xem 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 | Các tài liệu hỗ trợ từ phiên làm việc ban đầu |
| paymentMethodDetails | JSON | O | Phương thức thanh toán đã sử dụng. Xem đối tượng paymentMethodDetails bên dưới |
| 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. Xem Chữ ký |
Đối tượng fees
| Trường | Loại | Mô tả |
|---|---|---|
| buyer | Float | Số phí mà người mua phải trả |
| seller | Float | Số phí mà 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
| Trường | Loại | Mô tả |
|---|---|---|
| displayName | String | Nhãn phương thức thanh toán hiển thị cho người mua |
| 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 (ví dụ: card, wallet) |
{type} | JSON | Tùy chọn. Chi tiết cụ thể của phương thức thanh toán. Khóa bằng với giá trị type. Hiện tại chỉ có cho thanh toán thẻ khi có sẵn chi tiết thẻ. Xem đối tượng card bên dưới |
Đối tượng card (paymentMethodDetails.card)
| Trường | Mô tả |
|---|---|
| name | Tên chủ thẻ |
| firstSixDigits | 6 chữ số đầu tiên của số thẻ (BIN) |
| lastFourDigits | 4 chữ số cuối cùng của số thẻ |
| expiryMonth | Tháng hết hạn (MM) |
| expiryYear | Năm hết hạn (YY) |
| type | Thương hiệu thẻ (visa, mastercard, amex, jcb, v.v.) |
| issuer | Tên ngân hàng phát hành (tùy thuộc vào nhà cung cấp) |
| issuerCountryCode | Mã quốc gia ISO 3166-1 alpha-2 của ngân hàng phát hành (tùy thuộc vào nhà cung cấp) |
| funding | Loại nguồn tiền của thẻ: credit, debit, hoặc prepaid (tùy thuộc vào nhà cung cấp) |
| authorizationCode | Mã ủy quyền từ ngân hàng phát hành (tùy thuộc vào nhà cung cấp) |
| clientIP | Địa chỉ IP của khách hàng tại thời điểm thanh toán (tùy thuộc vào nhà cung cấp) |
| checks | Đối tượng kết quả xác minh AVS/CVC (tùy thuộc vào nhà cung cấp) |
| threeDSecure | Đối tượng chi tiết xác thực 3D Secure (tùy thuộc vào nhà cung cấp) |
Các trường trong đối tượng checks (nếu có):
| Trường | Mô tả |
|---|---|
| addressLine1Check | Kết quả kiểm tra dòng địa chỉ 1 của AVS |
| addressPostalCodeCheck | Kết quả kiểm tra mã bưu điện của AVS |
| cvcCheck | Kết quả kiểm tra CVC/CVV |
Các trường trong đối tượng threeDSecure (nếu có):
| Trường | Mô tả |
|---|---|
| authFlow | Luồng xác thực đã sử dụng |
| eci | Chỉ số thương mại điện tử (Electronic Commerce Indicator) |
| result | Kết quả xác thực 3DS |
| version | Phiên bản giao thức 3DS |
Ví dụ Payload IPN (Thanh toán thẻ thành công)
{
"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",
"card": {
"name": "John Doe",
"firstSixDigits": "411111",
"lastFourDigits": "1111",
"expiryMonth": "01",
"expiryYear": "30",
"type": "visa",
"issuer": "Example Bank",
"issuerCountryCode": "US",
"funding": "credit",
"authorizationCode": "ABC123"
}
},
"metadata": { "orderId": "12345" },
"message": null,
"descriptor": "GLODIPAY*ORDER-001",
"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 xác nhận
Máy chủ của bạn phải phản hồi với JSON sau đây trong vòng 30 giây. Bất kỳ phản hồi nào khác hoặc quá thời gian chờ đều được coi là gửi không thành công và GLODIPAY sẽ thực hiện gửi lại.
{
"returnCode": "100",
"description": "Received"
}
| Trường | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
| returnCode | String | M | Phải là "100" để xác nhận đã nhận thành công |
| description | String(max:1500) | O | Mô tả tùy chọn |
Refund IPN
Thông báo hoàn tiền sử dụng cùng một notificationUrl như giao dịch gốc. Định dạng payload sẽ khác — xem Refund API để biết các trường payload IPN cụ thể cho việc hoàn tiền.