2️Gọi API Refund

API Refund cho phép đối tác thực hiện hoàn tiền cho các giao dịch đã được thanh toán qua mã VietQR.

POST

https://<vietqr-host>/<basepath>/api/transaction/refund

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Body

Name	Type	Required	Description
bankAccount	String	Yes	TK ngân hàng của đối tác.
referenceNumber	String	Yes	Mã giao dịch (GD TT đang cần hoàn tiền).
amount	String	Yes	Số tiền cần hoàn tiền cho KH của đối tác.
content	String	Yes	Nội dung hoàn tiền.
checkSum	String	Yes	Chuỗi mã hóa MD5 các tham số: (secretKey+referenceNumber+ amount + bankAccount)
multiTimes	Boolean	Optional	Cho phép hoàn tiền nhiều lần. Chỉ có thể chọn vào lần hoàn tiền đầu tiên.
bankCode	String	Yes	Tên viết tắt của ngân hàng.
terminalCode	String	Optional	Mã cửa hàng/điểm bán.
subTerminalCode	String	Optional	Mã cửa hàng phụ/điểm bán phụ.

Response

200

{
    "status": "SUCCESS",
    "message": "mã_giao_dịch"
}

400

{
    "status": "FAILED",
    "message": "mã_lỗi_và_mô_tả_lỗi"
}

---

Code mẫu

cURL

curl --location 'https://api.vietqr.org/vqr/api/transaction/refund' \
--header 'Cookie: JSESSIONID=5CAD2D74C5EBDF9B1CAC5684F2DB47CE; JSESSIONID=C1711954475F66AE09967ADFFA4C80CD; JSESSIONID=F40E5CBDEEB02F82DF40BAD476A6222B' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdGJtZDFlV1Z1TFhWelpYSXlORGt5IiwiaWF0IjoxNzIxMjk3NjAxLCJleHAiOjE3MjEyOTc5MDF9.SEy2kqjhNup2UVaKhldXZQ1bVJn6o69LxgF9r0yA7zBqJWC5n9PhFUYk3G_oBsmCrAbobMohNHzJRsgqbwsUUA' \
--data '{
    "bankCode": "mã_ngân_hàng",
    "bankAccount": "tài_khoản_ngân_hàng_đồng_bộ",
    "referenceNumber": "mã_giao_dịch_đã_thanh_toán_cần_hoàn_tiền",
    "amount": "số_tiền_được_hoàn",
    "content": "nội_dung_hoàn_tiền",
    "multiTimes": "true: cho_phép_hoàn_tiền_nhiều_lần",
    "terminalCode": "mã_điểm_bán",
    "subTerminalCode": "mã_con_điểm_bán",
    "checkSum": "HASH MD5 128 bit: secret_key_do_vietqr_cung_cấp + referenceNumber + amount + bankAccount"
}'

---

Các câu hỏi thường gặp

secretKey tôi phải lấy ở đâu?

Sau khi bạn tích hợp xong dịch vụ thanh toán qua mã VietQR, hãy liên hệ đến bộ phận kỹ thuật của VietQR để được cấp secretKey.

API Refund hỗ trợ những loại giao dịch nào?

API Refund chỉ hỗ trợ hoàn tiền cho các giao dịch đã thanh toán qua mã VietQR và còn hiệu lực.

Làm thế nào để kiểm tra trạng thái hoàn tiền?

Bạn có thể kiểm tra trạng thái của yêu cầu hoàn tiền bằng cách gọi lại API Check Transaction với mã giao dịch hoặc mã đơn hàng.

Có giới hạn về số lần hoàn tiền cho một giao dịch không?

Tùy thuộc vào chính sách của VietQR và cấu hình của bạn, có thể có giới hạn về số lần hoàn tiền cho một giao dịch cụ thể.