4️Gọi API Generate VietQR Code

Dịch vụ cho phép đối tác tạo mã QR Code thanh toán để người dùng quét và thực hiện thanh toán trực tiếp. Tùy thuộc vào loại mã thanh toán VietQR, một số tham số khác nhau sẽ cần được truyền đi.

POST

https://dev.vietqr.org/vqr/api/qr/generate-customer

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token> bạn nhận được khi gọi API Get Token ở bước 5.

Body

Name	Type	Required	Description
bankCode	String	Yes	Mã ngân hàng của tài khoản.
bankAccount	String	Yes	Tài khoản ngân hàng tạo mã thanh toán VietQR.
userBankName	String	Yes	Họ tên chủ tài khoản. Không dấu tiếng Việt.
content	String	Yes	Nội dung chuyển tiền. Tối đa 19 ký tự, tiếng Việt không dấu, không ký tự đặc biệt.
qrType	Integer	Yes	Tùy loại mã thanh toán cần tạo, nhập giá trị tương ứng: - VietQR động: 0 - VietQR tĩnh: 1 - VietQR bán động: 3
amount	Long	Optional	Số tiền cần thanh toán. <Bắt buộc nếu "qrType" = 0 hoặc 3>
orderId	String	Optional	Mã ID giao dịch bên đối tác cần quản lý. “orderId” sẽ được trả về khi hệ thống nhận biến động số dư (có thông tin giao dịch trùng với giao dịch được tạo bằng mã QR). <Bắt buộc nếu "qrType" = 0>
transType	String	Optional	Phân loại giao dịch là ghi nợ/ghi có (giá trị: D/C). Mặc định là “C”. <Bắt buộc nếu "qrType" = 0>
terminalCode	String	Optional	Mã cửa hàng/điểm bán. <Bắt buộc nếu "qrType" = 1 hoặc 3>
serviceCode	String	Optional	Mã sản phẩm, dịch vụ được thanh toán. <Bắt buộc nếu "qrType" = 3>
subTerminalCode	String	Optional	Mã cửa hàng/điểm bán phụ.
sign	String	Optional	Chữ ký.
urlLink	String	Optional	Trang chuyển đến sau khi quét mã thanh toán.
note	String	Optional	Ghi chú cho giao dịch.
additionalData	Object	Optional	Các tham số truyền thêm.

Response

200 - mã QR động

{
    "bankCode": "mã_ngân_hàng",
    "bankName": "tên_ngân_hàng",
    "bankAccount": "tài_khoản_ngân_hàng_nhận",
    "userBankName": "tên_chủ_tài_khoản",
    "amount": "số_tiền_cần_thanh_toán",
    "content": "nội_dung_thanh_toán",
    "qrCode": "mã_QR_dạng_string",
    "imgId": "id_ảnh_ngân_hàng",
    "existing": "1: đã_được_tạo_trên_hệ_thống_vietQR_thành_công",
    "transactionId": "id_định_danh_của_QR",
    "transactionRefId": "mã_định_danh_của_QR",
    "qrLink": "mã_QR_dạng_link",
    "terminalCode": "mã_điểm_bán",
    "subTerminalCode": "mã_con_điểm_bán",
    "serviceCode": "mã_sản_phẩm",
    "orderId": "mã_đơn_hàng",
    "additionalData": "thông_tin_thêm"
}

200 - mã QR bán động

{
    "bankCode": "mã_ngân_hàng",
    "bankName": "tên_ngân_hàng",
    "bankAccount": "tài_khoản_ngân_hàng_nhận",
    "userBankName": "tên_chủ_tài_khoản",
    "amount": "số_tiền_cần_thanh_toán",
    "content": "nội_dung_thanh_toán",
    "qrCode": "mã_QR_dạng_string",
    "imgId": "id_ảnh_ngân_hàng",
    "existing": "1: đã_được_tạo_trên_hệ_thống_vietQR_thành_công",
    "transactionId": "id_định_danh_của_QR",
    "transactionRefId": "mã_định_danh_của_QR",
    "qrLink": "mã_QR_dạng_link",
    "terminalCode": "mã_điểm_bán",
    "subTerminalCode": "mã_con_điểm_bán",
    "serviceCode": "mã_sản_phẩm",
    "orderId": "mã_đơn_hàng",
    "additionalData": "thông_tin_thêm"
}

200 - mã QR tĩnh

{
    "bankCode": "mã_ngân_hàng",
    "bankName": "tên_ngân_hàng",
    "bankAccount": "tài_khoản_ngân_hàng_nhận",
    "userBankName": "tên_chủ_tài_khoản",
    "amount": "số_tiền_cần_thanh_toán",
    "content": "nội_dung_thanh_toán",
    "qrCode": "mã_QR_dạng_string",
    "imgId": "id_ảnh_ngân_hàng",
    "existing": "1: đã_được_tạo_trên_hệ_thống_vietQR_thành_công",
    "transactionId": "id_định_danh_của_QR",
    "transactionRefId": "mã_định_danh_của_QR",
    "qrLink": "mã_QR_dạng_link",
    "terminalCode": "mã_điểm_bán",
    "subTerminalCode": "mã_con_điểm_bán",
    "serviceCode": "mã_sản_phẩm",
    "orderId": "mã_đơn_hàng",
    "additionalData": "thông_tin_thêm"
}

400

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

---

Code tham khảo

cURL tạo mã QR động

curl --location 'https://dev.vietqr.org/vqr/api/qr/generate-customer' \
--header 'Cookie: JSESSIONID=5CAD2D74C5EBDF9B1CAC5684F2DB47CE; JSESSIONID=C1711954475F66AE09967ADFFA4C80CD; JSESSIONID=D4468C26FD481B215DBF12CB9707B0AD' \
--header 'Content-Type: application/json' \
--data '{
    "amount": "số_tiền_cần_thanh_toán",
    "content": "nội_dung_thanh_toán",
    "bankAccount": "tài_khoản_ngân_hàng_nhận",
    "bankCode": "mã_ngân_hàng",
    "userBankName": "tên_chủ_tài_khoản",
    "transType": "C:giao_dịch_đến/D:giao_dịch_đi",
    "orderId": "mã_đơn_hàng",
    "sign": "chữ_ký",
    "serviceCode": "mã_sản_phẩm",
    "qrType": "loại qr: 0",
    "terminalCode": "mã_điểm_bán",
    "subTerminalCode": "mã_con_điểm_bán",
    "note": "ghi_chú_mã_qr",
    "urlLink": "link_mà_trang_qr_link_sẽ_redirect_nếu_mã_qr_được_thanh_toán_thành công",
    "additionalData": "thông_tin_thêm_mã_QR_có_thể_truyền_empty_do_KH_tự_định_nghĩa",
}'

cURL tạo mã QR bán động

curl --location 'https://dev.vietqr.org/vqr/api/qr/generate-customer' \
--header 'Cookie: JSESSIONID=5CAD2D74C5EBDF9B1CAC5684F2DB47CE; JSESSIONID=C1711954475F66AE09967ADFFA4C80CD; JSESSIONID=D4468C26FD481B215DBF12CB9707B0AD' \
--header 'Content-Type: application/json' \
--data '{
    "amount": "số_tiền_của_sản_phẩm",
    "content": "nội_dung_thanh_toán",
    "bankAccount": "tài_khoản_ngân_hàng_nhận",
    "bankCode": "mã_ngân_hàng",
    "userBankName": "tên_chủ_tài_khoản",
    "transType": "C:giao_dịch_đến/D:giao_dịch_đi",
    "qrType": "loại qr: 1",
    "terminalCode": "mã_điểm_bán_đã_đồng_bộ"
    "serviceCode": "mã_sản_phẩm",
    "qrType": 3
}'

cURL tạo mã QR tĩnh

curl --location 'https://dev.vietqr.org/vqr/api/qr/generate-customer' \
--header 'Cookie: JSESSIONID=5CAD2D74C5EBDF9B1CAC5684F2DB47CE; JSESSIONID=C1711954475F66AE09967ADFFA4C80CD; JSESSIONID=A2494C77F9BCB561B15CDFDF6FF2CD1F' \
--header 'Content-Type: application/json' \
--data '{
    "content": "nội_dung_thanh_toán",
    "bankAccount": "tài_khoản_ngân_hàng_nhận",
    "bankCode": "mã_ngân_hàng",
    "userBankName": "tên_chủ_tài_khoản",
    "transType": "C:giao_dịch_đến/D:giao_dịch_đi",
    "qrType": "loại qr: 1",
    "terminalCode": "mã_điểm_bán_đã_đồng_bộ"
}'

---

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

Khi gọi API Generate VietQR Code, tôi gặp phải mã lỗi trả về là "E34"??!

Khi gặp phải mã lỗi này, bạn hãy kiểm tra lại 2 trường sau:

• content :

  • Độ dài không được vượt quá 19 ký tự.

  • Không chứa ký tự đặc biệt.

  • Ký tự thuộc dạng chữ cái Latin/Tiếng Việt không dấu.

• orderId :

  • Độ dài không được vượt quá 19 ký tự.

  • Không chứa ký tự đặc biệt.

  • Ký tự thuộc dạng chữ cái Latin/Tiếng Việt không dấu.

API Generate VietQR Code dùng để làm gì?

API Generate VietQR Code được sử dụng để tạo mã QR thanh toán cho các giao dịch. Mã QR này có thể được khách hàng quét để thực hiện thanh toán trực tiếp từ tài khoản ngân hàng.

Tôi cần cung cấp những thông tin gì để tạo mã QR thanh toán?

Để tạo mã QR thanh toán, bạn cần cung cấp các thông tin như số tiền, mã đơn hàng, thông tin người nhận, và thông tin tài khoản ngân hàng của người nhận. Các thông tin này sẽ được mã hóa vào mã QR. Bạn có thể xem chi tiết các thông tin cần thiết cho từng loại mã QR ở trên.

Làm thế nào để biết mã QR đã được tạo thành công?

Khi mã QR được tạo thành công, API sẽ trả về hình ảnh mã QR dưới dạng string cùng với các thông tin chi tiết liên quan đến giao dịch. Nếu có lỗi xảy ra, bạn sẽ nhận được thông báo lỗi trong phần phản hồi.

Làm thế nào để xử lý lỗi khi gọi API Generate VietQR Code?

Nếu bạn gặp lỗi khi gọi API, trước tiên hãy kiểm tra lại các thông tin đầu vào như số tiền, thông tin tài khoản, và mã đơn hàng. Đảm bảo rằng các thông tin này chính xác và hợp lệ. Nếu vấn đề vẫn tiếp diễn, hãy liên hệ với bộ phận hỗ trợ kỹ thuật của VietQR để được giúp đỡ.

Mã QR có thể được quét bằng ứng dụng nào?

Mã QR được tạo bởi API VietQR có thể được quét bằng bất kỳ ứng dụng ngân hàng nào hỗ trợ chuẩn thanh toán QR tại Việt Nam, hoặc các ứng dụng thanh toán ví điện tử có tính năng quét mã QR.

Tôi có cần mã hóa thông tin trước khi gửi đến API không?

Không, API VietQR sẽ tự động mã hóa các thông tin cần thiết khi tạo mã QR. Bạn chỉ cần đảm bảo rằng các thông tin gửi đến API là chính xác và đầy đủ.