5️⃣Gọi API Test Callback

API này được thiết kế để kiểm tra kết nối callback từ hệ thống VietQR đến hệ thống của đối tác. Đây là một phần của quá trình thử nghiệm và giả lập.

Lưu ý: API này chỉ có thể áp dụng ở môi trường Sandbox (TEST).

Giả Định Giao Dịch: Trong môi trường thử nghiệm này, API giả định rằng một giao dịch đã được hoàn thành và thanh toán.

POST

https://dev.vietqr.org/vqr/bank/api/test/transaction-callback

Headers

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

Body

Name	Type	Required	Description
bankAccount	String	Yes	Tài khoản ngân hàng tạo mã thanh toán VietQR.
content	String	Yes	Nội dung chuyển tiền. Bạn cần truyền đúng nội dung ở phần response khi tạo mã (bước 6).
amount	Long	Yes	Số tiền mà bạn đã tạo mã thanh toán ở bước 6.
transType	String	Yes	Phân loại giao dịch là ghi nợ/ghi có (giá trị: D/C). Mặc định là “C”.
bankCode	String	Yes	Mã ngân hàng. VD: "MB" cho ngân hàng MBBank.

Response

200

{
    "status": "SUCCESS",
    "message": "ID_của_giao_dịch"
}

400

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

---

Code mẫu

cURL

curl --location 'https://dev.vietqr.org/vqr/bank/api/test/transaction-callback' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdGJtZDFlV1Z1TFhWelpYSXlORGt5IiwiaWF0IjoxNzIxNDUwMzEzLCJleHAiOjE3MjE0NTA2MTN9.u0hK2fZVFvtaZQ3jyVJmMvhyqW8aRFGJIgpL8C71jtXbAPfPhqyJIdGc0Lv-XOY7e1NcjZQWH3FUhc4SXxgqlQ' \
--header 'Cookie: JSESSIONID=5DAD675C6D1BFEB2305B2340FE3BEDEC' \
--data '{
    "bankAccount": "tài_khoản_ngân_hàng_đồng_bộ",
    "content": "nội_dung_test_callback_là_nội_dung_khi_quét_mã_qr_thanh_toán",
    "amount": "số_tiền",
    "bankCode": "mã_ngân_hàng", //VD: "MB" cho ngân hàng MBBank.
    "transType": "C:giao_dịch_đến, D:giao_dịch_đi"
}'

---

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

API Test Callback dùng để làm gì?

API Test Callback được sử dụng để kiểm tra khả năng tiếp nhận và xử lý callback từ hệ thống của VietQR đến hệ thống của bạn. Nó giúp xác minh rằng hệ thống của bạn có thể nhận và xử lý thông báo từ VietQR khi có sự kiện xảy ra.

Tại sao cần phải thực hiện Test Callback?

Thực hiện Test Callback giúp đảm bảo rằng hệ thống của bạn có thể nhận thông báo (callback) một cách chính xác từ VietQR, điều này rất quan trọng trong việc đồng bộ trạng thái giao dịch và phản hồi kịp thời cho khách hàng.

Khi nào nên thực hiện Test Callback?

Bạn nên thực hiện Test Callback sau khi đã cấu hình xong các endpoint cần thiết trên hệ thống của mình và trước khi triển khai dịch vụ vào môi trường sản xuất. Điều này giúp phát hiện và khắc phục sớm các vấn đề tiềm ẩn.

Làm thế nào để kiểm tra rằng hệ thống của tôi đã nhận đúng callback?

Bạn có thể theo dõi log hệ thống của mình hoặc kiểm tra các phản hồi từ API Test Callback để xác nhận rằng hệ thống đã nhận đúng callback và xử lý nó theo mong đợi.

Phản hồi của API Test Callback sẽ như thế nào?

API Test Callback sẽ gửi một yêu cầu HTTP POST đến endpoint của API Transaction Sync mà bạn đã cấu hình, với dữ liệu mô phỏng giao dịch đã được thanh toán thực tế. Hệ thống của bạn cần trả về một phản hồi HTTP 200 OK để xác nhận rằng callback đã được nhận và xử lý thành công.

Sau khi tôi gọi API Test Callback thành công, nhưng vẫn chưa nhận được báo có giao dịch từ API Transaction Sync?

Hãy truyền đúng 2 trường content và amount được trả về ở phần response lúc tạo mã ở bước 6.

Nếu callback không được xử lý thành công thì cần làm gì?

Nếu callback không được xử lý thành công, bạn cần kiểm tra lại cấu hình endpoint, logic xử lý callback trên hệ thống của bạn, và thử lại Test Callback. Kiểm tra log và các thông báo lỗi để xác định nguyên nhân và khắc phục.

Có thể thực hiện Test Callback bao nhiêu lần?

Bạn có thể thực hiện Test Callback nhiều lần cho đến khi đảm bảo rằng hệ thống của bạn có thể xử lý callback một cách chính xác và ổn định.

Làm thế nào để xác nhận rằng callback đã được xử lý đúng cách?

Sau khi nhận được callback, hệ thống của bạn cần thực hiện các bước xử lý theo yêu cầu và gửi phản hồi HTTP 200 OK. Kiểm tra log hệ thống để đảm bảo rằng tất cả các bước đã được thực hiện đúng.