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

{
    "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"
}

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_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",
}'

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 đủ.

Last updated