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 23 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. Khi thanh toán thành công sẽ trả về tự động.

note

String

Optional

Ghi chú cho giao dịch.

additionalData

Object

Optional

Các tham số truyền thêm.

Response

// Ví dụ kết quả trả về mã QR động
{
    "bankCode": "MB",
    "bankName": "Ngân hàng TMCP Quân đội",
    "bankAccount": "0852240768",
    "userBankName": "HA TRUNG HIEU",
    "amount": "2000",
    "content": "VQR1425e9ae32 Push QR Test VietQR SOVABA",
    "qrCode": "00020101021138540010A00000072701240006970422011008522407680208QRIBFTTA5303704540420005802VN62440840VQR1425e9ae32 Push QR Test VietQR SOVABA6304C9E4",
    "imgId": "58b7190b-a294-4b14-968f-cd365593893e",
    "existing": 1,
    "transactionId": "",
    "transactionRefId": "MjM2NTJkNTgtY2ExYS00YjEwLTgwMGYtZDZmMzc1ZTM3NTcy",
    "qrLink": "https://pro.vietqr.vn/test/qr-generated?token=MjM2NTJkNTgtY2ExYS00YjEwLTgwMGYtZDZmMzc1ZTM3NTcy",
    "terminalCode": null,
    "subTerminalCode": "",
    "serviceCode": "",
    "orderId": "TestQRCODESOVABA",
    "additionalData": []
}

{
    "bankCode": "mã_ngân_hàng",
    "bankName": "tên_ngân_hàng",
    "bankAccount": "tài_khoản_ngân_hàng_nhận",
    "userBankName": "tên_chủ_tài_khoản",
    "amount": "số_tiền_cần_thanh_toán",
    "content": "nội_dung_thanh_toán",
    "qrCode": "mã_QR_dạng_string",
    "imgId": "id_ảnh_ngân_hàng",
    "existing": "1: đã_được_tạo_trên_hệ_thống_vietQR_thành_công",
    "transactionId": "id_định_danh_của_QR",
    "transactionRefId": "mã_định_danh_của_QR",
    "qrLink": "mã_QR_dạng_link",
    "terminalCode": "mã_điểm_bán",
    "subTerminalCode": "mã_con_điểm_bán",
    "serviceCode": "mã_sản_phẩm",
    "orderId": "mã_đơn_hàng",
    "additionalData": "thông_tin_thêm"
}

{
    "bankCode": "mã_ngân_hàng",
    "bankName": "tên_ngân_hàng",
    "bankAccount": "tài_khoản_ngân_hàng_nhận",
    "userBankName": "tên_chủ_tài_khoản",
    "amount": "số_tiền_cần_thanh_toán",
    "content": "nội_dung_thanh_toán",
    "qrCode": "mã_QR_dạng_string",
    "imgId": "id_ảnh_ngân_hàng",
    "existing": "1: đã_được_tạo_trên_hệ_thống_vietQR_thành_công",
    "transactionId": "id_định_danh_của_QR",
    "transactionRefId": "mã_định_danh_của_QR",
    "qrLink": "mã_QR_dạng_link",
    "terminalCode": "mã_điểm_bán",
    "subTerminalCode": "mã_con_điểm_bán",
    "serviceCode": "mã_sản_phẩm",
    "orderId": "mã_đơn_hàng",
    "additionalData": "thông_tin_thêm"
}

{
    "bankCode": "mã_ngân_hàng",
    "bankName": "tên_ngân_hàng",
    "bankAccount": "tài_khoản_ngân_hàng_nhận",
    "userBankName": "tên_chủ_tài_khoản",
    "amount": "số_tiền_cần_thanh_toán",
    "content": "nội_dung_thanh_toán",
    "qrCode": "mã_QR_dạng_string",
    "imgId": "id_ảnh_ngân_hàng",
    "existing": "1: đã_được_tạo_trên_hệ_thống_vietQR_thành_công",
    "transactionId": "id_định_danh_của_QR",
    "transactionRefId": "mã_định_danh_của_QR",
    "qrLink": "mã_QR_dạng_link",
    "terminalCode": "mã_điểm_bán",
    "subTerminalCode": "mã_con_điểm_bán",
    "serviceCode": "mã_sản_phẩm",
    "orderId": "mã_đơn_hàng",
    "additionalData": "thông_tin_thêm"
}

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

Code tham khảo

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_toán",
    "content": "nội_dung_thanh_toán",
    "bankAccount": "tài_khoản_ngân_hàng_nhận",
    "bankCode": "mã_ngân_hàng",
    "userBankName": "tên_chủ_tài_khoản",
    "transType": "C:giao_dịch_đến/D:giao_dịch_đi",
    "orderId": "mã_đơn_hàng",
    "sign": "chữ_ký",
    "serviceCode": "mã_sản_phẩm",
    "qrType": "loại qr: 0",
    "terminalCode": "mã_điểm_bán",
    "subTerminalCode": "mã_con_điểm_bán",
    "note": "ghi_chú_mã_qr",
    "urlLink": "link_mà_trang_qr_link_sẽ_redirect_nếu_mã_qr_được_thanh_toán_thành công",
    "additionalData": "thông_tin_thêm_mã_QR_có_thể_truyền_empty_do_KH_tự_định_nghĩa",
}'

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_của_sản_phẩm",
    "content": "nội_dung_thanh_toán",
    "bankAccount": "tài_khoản_ngân_hàng_nhận",
    "bankCode": "mã_ngân_hàng",
    "userBankName": "tên_chủ_tài_khoản",
    "transType": "C:giao_dịch_đến/D:giao_dịch_đi",
    "qrType": "loại qr: 1",
    "terminalCode": "mã_điểm_bán_đã_đồng_bộ"
    "serviceCode": "mã_sản_phẩm",
    "qrType": 3
}'

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_toán",
    "bankAccount": "tài_khoản_ngân_hàng_nhận",
    "bankCode": "mã_ngân_hàng",
    "userBankName": "tên_chủ_tài_khoản",
    "transType": "C:giao_dịch_đến/D:giao_dịch_đi",
    "qrType": "loại qr: 1",
    "terminalCode": "mã_điểm_bán_đã_đồ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 đủ.

PreviousGọi API Get Token NextGọi API Test Callback

Last updated 9 days ago