2️Calling the Refund API

The Refund API allows partners to process refunds for transactions that have been paid through the VietQR code.

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	The bank account of the partner.
referenceNumber	String	Yes	The transaction ID that needs to be refunded.
amount	String	Yes	The amount to be refunded to the customer of the partner.
content	String	Yes	Description of the refund.
checkSum	String	Yes	An MD5 hash of the parameters: (secretKey + referenceNumber + amount + bankAccount).
multiTimes	Boolean	Optional	It allows for multiple refunds. Only the first refund can be selected for processing.
bankCode	String	Yes	The abbreviated name of the bank.
terminalCode	String	Optional	The code for the store or point of sale.
subTerminalCode	String	Optional	The code for the sub-store or sub-point of sale.

Response

200

{
    "status": "SUCCESS",
    "message": "transaction_code"
}

400

{
    "status": "FAILED",
    "message": "error_code_and_description"
}

---

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": "bank_code", // Bank code
    "bankAccount": "bank_account", // Bank account of the partner
    "referenceNumber": "transaction_code_that_needs_refund", // The transaction code that needs to be refunded
    "amount": "amount_to_refund", // The amount to be refunded
    "content": "refund_content", // The content of the refund
    "multiTimes": "true", // Allows multiple refunds
    "terminalCode": "terminal_code", // Terminal code
    "subTerminalCode": "sub_terminal_code", // Sub-terminal code
    "checkSum": "MD5_HASH" // MD5 hash: secret_key_provided_by_vietqr + referenceNumber + amount + bankAccount
}'

---

FAQs

Where do I get the secretKey?

After you have successfully integrated the payment service via VietQR, please contact the technical department of VietQR to obtain the secretKey.

What types of transactions does the API Refund support?

The API Refund only supports refunds for transactions that have been paid through VietQR and are still valid.

How can I check the refund status?

You can check the status of the refund request by calling the API Check Transaction with the transaction code or order code.

Is there a limit on the number of refunds for a single transaction?

Depending on VietQR's policies and your configuration, there may be a limit on the number of refunds for a specific transaction.