Refund API

Ask AI

Khởi tạo hoàn tiền cho các giao dịch đã hoàn tất và truy vấn trạng thái của chúng.

---

Khởi tạo hoàn tiền (Initiate Refund)

Endpoint: POST /v2/refund
Content-Type: application/json

Hoàn tiền có thể là toàn phần (full) hoặc một phần (partial) (tùy thuộc vào các ràng buộc của từng nhà cung cấp — một số nhà cung cấp chỉ hỗ trợ hoàn tiền toàn bộ số tiền). Việc hoàn tiền có thể được xử lý tự động ngay lập tức hoặc được giữ lại để phê duyệt thủ công, tùy thuộc vào cấu hình của người bán.

Số tiền hoàn trả tối đa cho mỗi lần hoàn tiền là: paidAmount trừ đi tổng số tiền đã được hoàn trả cho giao dịch đó.

Yêu cầu (Request)

Trường	Loại	Bắt buộc	Mô tả
transactionId	String (ULID)	M	ID giao dịch (transactionId) từ IPN hoặc truy vấn giao dịch. Ví dụ: 01jza90dy6w82dfrrqvadn5vs4
amount	Float	M	Số tiền hoàn lại. Tối thiểu: 0.10. Tối đa: số tiền còn lại có thể hoàn trả. Ví dụ: 50.00
reason	String(max:1000)	O	Mô tả ngắn gọn về lý do hoàn tiền. Ví dụ: Yêu cầu của khách hàng
signature	String(max:750)	M	Chữ ký RSA-MD5. Xem Chữ ký

Một số nhà cung cấp nhất định (PayAgency, SmartPay, ClisaPay, FinvyPay, WPay) chỉ hỗ trợ hoàn tiền toàn bộ số tiền.

Phản hồi (Response)

Tất cả các phản hồi được đóng gói:

Trường	Loại	Mô tả
status	String	success hoặc error
message	String	Thông báo dễ hiểu cho người dùng
data	JSON	Chi tiết hoàn tiền. Xem đối tượng dữ liệu (data object) bên dưới

Đối tượng dữ liệu (data object):

Trường	Loại	Mô tả
refundId	String (ULID)	ID hoàn tiền của GLODIPAY
refundNumber	String	Số hoàn tiền dễ hiểu của GLODIPAY

Được xử lý tự động ngay lập tức:

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

Đ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."]
    }
  ]
}

---

Truy vấn trạng thái hoàn tiền (Query Refund Status)

Endpoint: POST /v2/refund/query
Content-Type: application/json

Yêu cầu (Request)

Trường	Loại	Bắt buộc	Mô tả
refundId	String (ULID)	M	ID hoàn tiền của GLODIPAY (từ phản hồi Refund API hoặc Refund IPN). Ví dụ: 01jzabk09xc4pbgwe8hyg4cwbf
signature	String(max:750)	M	Chữ ký RSA-MD5. Xem Chữ ký

Phản hồi (Response)

Trường	Loại	Mô tả
status	String	success
message	String	Thông báo dễ hiểu cho người dùng
data	JSON	Đối tượng chi tiết hoàn tiền

Các trường trong đối tượng dữ liệu (data object fields):

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

Ví dụ:

{
  "status": "success",
  "message": "",
  "data": {
    "transactionId": "01jza90dy6w82dfrrqvadn5vs4",
    "ref": "ORDER-001",
    "refundId": "01jzabk09xc4pbgwe8hyg4cwbf",
    "currency": "USD",
    "refundAmount": 50.00,
    "status": "refund_successful",
    "statusCode": 11,
    "metadata": { "orderId": "12345" },
    "reason": "Customer request",
    "message": null,
    "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"
  }
}

---

Thông báo Refund IPN

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

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 trả về {"returnCode":"100"} trong vòng 30 giây, GLODIPAY sẽ thực hiện gửi lại.

Payload

Trường	Loại	Bắt buộc	Mô tả
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 Mã trạng thái
statusCode	Number	M	Mã trạng thái số
metadata	JSON	O	Các cặp khóa-giá trị từ phiên làm việc 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

Ví dụ Payload IPN:

{
  "transactionId": "01jza90dy6w82dfrrqvadn5vs4",
  "ref": "ORDER-001",
  "refundId": "01jzabk09xc4pbgwe8hyg4cwbf",
  "currency": "USD",
  "refundAmount": 50.00,
  "status": "refund_successful",
  "statusCode": 11,
  "metadata": { "orderId": "12345" },
  "reason": "Customer request",
  "message": null,
  "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"
}

Xác nhận (Acknowledgement)

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

{
  "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
description	String(max:1500)	O	Mô tả tùy chọn

---

Nguồn

Trang này được bắt nguồn từ GLODIPAY_Refund_API_Specification_v2.