# API VIETQR - Host2Host **TÀI LIỆU TÍCH HỢP DỊCH VỤ** **THANH TOÁN QUA MÃ VIETQR** ### **I. Ngữ cảnh** #### **Mô tả tài liệu** * Dịch vụ dành cho các đối tác nền tảng có nhu cầu tích hợp tính năng thanh toán qua mã VietQR. * Dịch vụ cho phép khách hàng thực hiện các giao dịch thanh toán bằng mã VietQR trực tiếp trên các nền tảng tích hợp. * Tài liệu này cung cấp thông tin nghiệp vụ: * Kích hoạt dịch vụ thanh toán bằng mã VietQR. * Đồng bộ thông tin thanh toán, thông tin tài khoản ngân hàng của khách hàng. * Tạo mã VietQR. * Nhận thông báo biến động số dư. * Tài liệu này cung cấp thông tin kỹ thuật: * Thông tin bảo mật. * Cấu hình kết nối dịch vụ. * Bộ API Services kết nối dịch vụ. * Thuật ngữ viết tắt: | **Thuật ngữ** | **Chú thích nội dung** | | ------------- | ----------------------------- | | ĐTNT | Đối tác nền tảng | | KH | Khách hàng | | TK/TKNH | Tài khoản/Tài khoản ngân hàng | | LK | Liên kết | | GD | Giao dịch | | TT | Thanh toán | | BĐSD | Biến động số dư | #### **Nghiệp vụ** **2.1. Luồng nghiệp vụ** ![](https://2094581354-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHIyMp8uez10XaYkjnjT8%2Fuploads%2F312aCajpDbMJxhhMFZWh%2F0.png?alt=media) ![](https://2094581354-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHIyMp8uez10XaYkjnjT8%2Fuploads%2FAB3iHLhoROGcSmD7y5jx%2F1.png?alt=media) **2.2. Mô tả luồng nghiệp vụ** **2.2.1. Luồng nghiệp vụ kích hoạt dịch vụ thanh toán bằng mã VietQR** | **Bước thực hiện** | **Người thực hiện** | **Hệ thống** | **Mô tả** | | ------------------ | ------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Pre-condition | KH | | Đã liên kết TK MBBank hoặc TK BIDV trên hệ thống VietQR. | | 1 | KH | ĐTNT | KH đăng ký dịch vụ thanh toán bằng mã VietQR trên ĐTNT. | | 2 | ĐTNT | VietQR | | | 3 | KH | VietQR | | | 4 | KH | VietQR | | | 5 | VietQR | ĐTNT | | **2.2.2. Luồng nghiệp vụ thanh toán qua mã VietQR** | **Bước thực hiện** | **Người thực hiện** | **Hệ thống** | **Mô tả** | | ------------------ | ------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | Pre-condition | KH | | | | 1 | KH | ĐTNT | Tạo đơn hàng/giao dịch cần thanh toán trên hệ thống ĐTNT. | | 2 | ĐTNT | VietQR | | | 3 | KH | ĐTNT | Khách hàng thực hiện thanh toán qua mã VietQR ĐTNT. | | 4 | VietQR | ĐTNT | VietQR trả thông tin BĐSD cho ĐTNT, đánh dấu giao dịch TT thành công. | **2.3. Kích hoạt dịch vụ thanh toán bằng mã VietQR** * Nghiệp vụ kích hoạt dịch vụ thanh toán bằng mã VietQR nhằm mục đích là xác thực thông tin của người dùng đăng ký dịch vụ. Đồng thời hệ thống VietQR và ĐTNT ghi nhận thông tin đăng ký dịch vụ. * Hệ thống VietQR cần xác nhận được khách hàng đăng ký dịch vụ thanh toán qua mã VietQR thông qua nền tảng nào. Các thông tin liên quan tới thông tin TKNH, thông tin TT. **2.4. Tạo mã VietQR** * ĐTNT sử dụng API tạo mã VietQR để tạo mã QR, mã VietQR này ứng với 1 giao dịch mới có trạng thái “Chờ TT”. * ĐTNT có thể đánh dấu giao dịch thông qua các tham số: * orderId: Là mã đơn hàng. * terminalCode: Là mã cửa hàng/điểm bán. * Thời hạn khả dụng cho 1 mã VietQR là 15 phút. Nếu hết thời gian khả dụng cho 1 mã VietQR thanh toán, KH/ĐTNT phải tạo lại một mã VietQR thanh toán mới. * Để sử dụng công cụ quản lý và thống kê cửa hàng hiệu quả trên hệ thống VietQR, KH cần thực hiện bước đồng bộ cửa hàng/điểm bán của mình lên hệ thống VietQR. Thông tin liên hệ kỹ thuật của VietQR. **2.5. Nhận thông báo Biến động số dư** * Hiện tại, hệ thống VietQR khả dụng dịch vụ nhận thông báo biến động số dư cho TKNH BIDV và MBBank. * Hệ thống VietQR chấp nhận loại TKNH cá nhân và TKNH doanh nghiệp. * Đối soát là quy trình đánh dấu trạng thái giao dịch. Một GD mới được khởi tạo với trạng thái là “Chờ TT”, khi KH TT thành công và hệ thống VietQR khớp được GD, GD được chuyển trạng thái từ “Chờ TT” sang “TT thành công”. * Các lưu ý khi nhận BĐSD: * Đối với KH sử dụng gói dịch vụ VietQR Plus: * Khi quét mã VietQR để thanh toán, nếu KH thay đổi số tiền + nội dung chuyển khoản, hệ thống VietQR sẽ không đối soát được giao dịch tương ứng với mã VietQR đã tạo. * Trong trường hợp không đối soát thành công, hệ thống VietQR vẫn ghi nhận KH có GD mới. Tuy nhiên, giao dịch được tạo từ mã VietQR trước đó sẽ không được đánh dấu trạng thái “TT thành công”. * Trong trường hợp đối soát thành công, hệ thống VietQR ghi nhận KH đã “TT thành công” giao dịch được tạo từ mã VietQR trước đó. * Đối với KH sử dụng gói dịch vụ VietQR Pro: * Khi quét mã VietQR để thanh toán, KH có thể thay đổi nội dung thanh toán mà không ảnh hưởng tới quy trình đối soát giao dịch. * Khi quét mã VietQR để thanh toán, trong trường hợp KH thay đổi số tiền chuyển khoản, hệ thống sẽ đánh dấu GD thất bại và từ chối chuyển khoản. Thông báo sẽ được hiển thị trực tiếp trên các app banking/ví điện tử của phía KH chuyển tiền. * Trong trường hợp đối soát thành công, hệ thống VietQR ghi nhận KH đã “TT thành công” giao dịch được tạo từ mã VietQR trước đó. ### **II. Thông tin kỹ thuật** #### **Quy định về xác thực bảo mật** * ĐTNT sử dụng **API Get Certificate** để lấy thông tin và hiển thị mã QR xác thực định danh KH trên hệ thống ĐTNT. * ĐTNT sử dụng **API Get User Information** để lấy thông tin xác thực **Bearer Token**. Đoạn **Bearer Token** này dùng để gọi **API Tạo mã VietQR**. * VietQR sẽ cung cấp 1 đoạn “**secretKey**” cho các ĐTNT để xác thực và mã hoá thông tin. * Quy định mã hoá thông tin dựa vào “**secretKey**”: * Secret Key: Liên hệ kỹ thuật VietQR để được cung cấp thông tin. * Đối với **API Get Certificate** và **API Get User Information**, hệ thống yêu cầu field “**checksum**” trong Request Body. Phía VietQR cung cấp thông tin để ĐTNT generate checksum: | **API** | **Quy định checksum** | | ------------------------ | ----------------------- | | API Get Certificate | MD5(secretKey + userId) | | API Get User Information | MD5(secretKey + userId) | * Quy định về thông tin xác thực **Bearer Token**: * Thời gian hiệu lực: **59 giây**. * Đoạn **Bearer Token** đánh dấu thông tin khách hàng sử dụng dịch vụ thanh toán qua mã VietQR, được sử dụng trên hệ thống ĐTNT. Vì vậy, ĐTNT không thể sử dụng đoạn 1 Bearer Token cho tất cả các KH. #### **Quy định về quy trình kết nối dịch vụ** * ĐTNT và KH tuân thủ theo quy trình kết nối dịch vụ để đảm bảo hệ thống vận hành một cách hiệu quả nhất, giảm thiểu rủi ro không mong muốn. * ĐTNT có 2 phương án để nhận phản hồi thông tin từ phía VietQR trả về: * Phương án 1: Đối tác thực hiện implement webhook để nhận thông tin phản hồi. Hệ thống VietQR yêu cầu các webhook phục vụ cho các mục đích sau: * Nhận thông báo kích hoạt dịch vụ thành công. * Nhận thông tin hiển thị mã VietQR. * Nhận thông báo BĐSD. * Phương án 2: Đối tác thực hiện implement Websocket của phía VietQR cung cấp để nhận thông tin phản hồi. Websocket sẽ phản hồi cho các mục đích sau: * Nhận thông báo kích hoạt dịch vụ thành công. * Nhận thông tin hiển thị mã VietQR. * Nhận thông báo BĐSD. * Thông tin webhook yêu cầu đáp ứng bảo mật bằng field “**checksum**”. * Websocket được trả về tương ứng với mỗi KH đăng ký dịch vụ. ĐTNT lấy thông tin webhook từ **API Get User Information**. ### **III. Mô tả APIs và Web Socket** #### **API Get Certificate** * 1. URL: 2. Method: POST 3. Request Body: * Xác thực: Bearer auth. | **Field** | **Type** | **Description** | | --------- | -------- | --------------------------------------------------------------------- | | webhook | String | webhook dùng để đăng ký dịch vụ | | checkSum | String |

Do VietQR cung cấp với định dạng

MD5(secretKey + userId)

| * 1. Response: | **Field** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------------------------------------------- | | qrCertificate | String | Mã QR dùng để hiển thị đối với máy box QR mới được lưu dưới firmware | | certificateId | String | certificateId (Dùng để kết nối websocket) | #### **API Get User Information** * URL: * Method: GET * Xác thực: Bearer. * Mô tả: * API dùng để xem chi tiết thông tin của máy QR Box * Request Param: | **Param** | **Type** | **Description** | | --------- | -------- | --------------------------------------------------------------------- | | userId | String | Id của user mà muốn lấy thông tin | | checkSum | String |

Do VietQR cung cấp với định dạng

MD5(secretKey + userId)

| * Response: | **Field** | **Type** | **Description** | | ---------------- | -------- | -------------------------------------------- | | userId | String | ID của KH | | phoneNo | String | Số điện thoại của KH | | bankAccount | String | Số TK ngân hàng được liên kết của KH | | userBankName | String | Tên chủ TK ngân hàng được liên kết | | bankCode | String | Mã của NH | | bankShortName | String | Tên viết tắt của ngân hàng | | registerPlatform | String | nền tảng đăng ký của KH | | address | String | Địa chỉ KH đăng ký | | qrCode | String | Mã QR Code hiển thị dùng để thanh toán | #### **API Tạo mã VietQR** * URL: * Method: POST * Request Body: | **Field** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------- | | bankAccount | String | Số TK ngân hàng đã liên kết | | bankName | String | Tên ngân hàng đã liên kết | | bankShortName | String | Tên viết tắt của ngân hàng đã liên kết | | userBankName | String | Tên chủ TK ngân hàng đã liên kết | | note | String | Ghi chú giao dịch | | amount | String | Số tiền gán trên giao dịch | | content | String | Nội dung chuyển khoản gán trên giao dịch | | imgId | String | Mã id hình ảnh của ngân hàng | | qrCode | String | Mã QR Code của giao dịch QR động | | transType | String | Loại giao dịch đến “C” hoặc đi “D” | | bankCode | String | Mã code của ngân hàng | | orderId | String | Mã giao dịch gán với giao dịch | | terminalCode | String | Mã code cửa hàng để đối soát | * Response: | **Field** | **Type** | **Description** | | --------- | -------- | ----------------------------------------------- | | status | String | “SUCCESS” or “FAILED” | | message | String |

SUCCESS: “”

FAILED: “E05” or “E46”

| #### #### **Web Socket nhận thông báo** * Websocket:: wss\://api.vietqr.org/vqr/socket?userId={userId} * Mô tả: Web Socket dùng để nhận BĐSD khi có giao dịch tới * Method: POST * Response: | **Field** | **Type** | **Description** | | -------------------- | -------- | ----------------------------------------------------------------- | | notificationType | String | Mã của notificationType ‘N05’: Mã code nhận biết BĐSD tới | | notificationId | String | Mã định danh của thông báo lưu dưới hệ thống VietQR | | transactionReceiveId | String | Mã định danh của giao dịch lưu dưới hệ thống VietQR | | bankAccount | String | Số TK của TK nhận BĐSD | | bankName | String | Tên TK ngân hàng của TK nhận BĐSD | | bankCode | String | Mã code của TK ngân hàng của TK nhận BĐSD | | bankId | String | Mã định danh của TK ngân hàng lưu dưới hệ thống | | terminalName | String | Tên cửa hàng (Mặc định ‘’) | | terminalCode | String | Mã code của cửa hàng (Mặc định ‘’) | | rawTerminalCode | String | Mã code cửa hàng raw (Mặc định ‘’) | | content | String | Nội dung chuyển khoản | | orderId | String | Mã đơn hàng của giao dịch | | referenceNumber | String | Mã code giao dịch của giao dịch | | amount | String | Số tiền của giao dịch | | timePaid | String | Thời gian thanh toán giao dịch | | type | String | Loại giao dịch | | time | String | Thời gian tạo giao dịch | | refId | String | Mã định danh của giao dịch đánh dấu của ngân hàng | | status | String |

0: Chờ thanh toán

1: Thành công

2: Đã hủy

| | traceId | String | Mã trace của transaction | | transType | String |

C: Giao dịch đến

D: Giao dịch đi

| | urlLink | String | Mặc định ‘’ | ### **IV. Mô tả Webhook** * Mô tả: Webhook là một cơ chế cho phép một ứng dụng gửi thông báo hoặc dữ liệu tới các ứng dụng khác một cách tự động khi một sự kiện cụ thể xảy ra. * Thiết lập webhook: Người dùng hoặc ứng dụng đăng ký một URL (được gọi là webhook endpoint) với một dịch vụ. URL này sẽ nhận các thông báo về sự kiện từ dịch vụ đó. ( VD: ) * Khi KH quét mã QR để thanh toán thì hệ thống sẽ gửi yêu cầu POST đến URL đã đăng ký về thông tin của đơn thành mà KH thanh toán