VietQR API 技术文档 (cn)
API - 生成 VietQR 代码和接收余额对账变动的技术连接文档.
跨平台支付連線API
(Power by |Vietqr.vn | Vietqr.com | Vietqr.org |)
Ver.20240120.APIVietqr
最近更新日期：2024 年 1 月 20 日
聯絡方式與支援：19006234 或 Dung 0939603636
日期變更 | 地點 改變 | 原因 | 修改人員 | 舊版
| 變更說明 | 新版本 |
20 Sep 2023 | None | 更新格式以方便檢索文檔 | Phạm Đức Hiếu DEV | Ver.20230913 | 新增說明 | Ver.20230913 |
20 Jan 2024 | None | 更新格式以方便檢索文檔 | Phạm Đức Hiếu DEV | Ver.20240120 | 調整格式 | Ver.20240120 |
|
|
|
|
|
|
|
1 - 介紹
該API旨在支援跨平台支付連接，為自動販賣機、物聯網設備和電子商務網站提供靈活且便利的解決方案。
主要特徵：
● API 返回支付交易回呼 支援二維碼：創建二維碼透過越南銀行和電子錢包的應用程式進行支付。
●實用工具：語音支付金額API
●二維碼支援越南各銀行APP及電子錢包支付
2. 目標使用者群體
● 此API適用於：
● 自動販賣機和物聯網設備：輕鬆整合以接收交易回呼並執行自動支付訂單匹配。
● 使用CRM、ERP、會計軟體、銷售軟體等需要連接自動付款對帳的軟體系統的客戶。
● 建立動態二維碼：使用VietQR連結建立動態二維碼，支援靈活支付。
3 - prepare
Understand Technical Documentation:
Read technical documentation about API connectivity.
References: Technical documents.
Register and Install VietQR:
Download and register an account on the VietQR application.
Registration instructions: Video instructions.
Download the application
Android: VietQR - Google Play
iOS: VietQR VN - App Store
Web: VietQR.vn
Link Bank Account with VietQR:
Link your MBBank bank account with VietQR application.
Linked instructions: Instructional website and Instructional video.
Setting up the Test Environment and Checking the Connection:
Provide necessary information for the test environment (domain/IP&Port, apiGetToken, apiCallback, username, password, bankAccount).
VietQR will provide username and password for API get token.
Switch to Real Environment (Golive):
Complete necessary procedures and documents.
Update final information to connect.
Perform Accepted test.
VietQR will golive and notify you.
Create a connection test environment
Contact for instructions:
Create your own on the portal : VietQR.vn
2 - API Technical Documentation
2.1. Get Token API
Environment: UAT
URL: http://112.78.1.220:8084/vqr/api/token_generate
method: POST
2.1. API get Token:
Environment: UAT
URL:
Method: POST
Authorization:
Parameter | Value |
Type | Basic Authentication |
Username | Taken from the system that creates the test environment |
Password | Taken from the test environment creation system |
Headers:
Parameter | Value |
Authorization | Basic [username:password] |
Content-Type | Application/json |
Output:
Parameter | Value | Type |
access_token | The token is returned to call other APIs in the system | String |
token_type | Default: Bearer Token | String |
expires_in | Token expiration time. Default is 59 seconds | String |
2.2 VIETQR CODE GENERATION API :
Test Environment (UAT)
Method: POST
Headers:
Parameter | Value |
Authorization | Bearer Token lấy từ API get Token |
Content-Type | Application/json |
Input:
Parameter | Value | Type |
bankAccount | Bank account generates VietQR code | String* |
amount | Amount of money | Long/String* |
content | Money transfer content. Maximum 19 characters, Vietnamese without accents, no special characters. | String* |
bankCode | Bank code. List of bankCode: https://docs.google.com/spreadsheets/d/1073HBsF1thj4vKc2pTVKh73YAOFUKaySRa8_kSOEzJs/edit?usp=sharing | String* |
transType | Debit/credit transaction (value: D/C). Default is “C”. | String* |
userBankName | Full name of account holder. (If the account is already linked to the VietQR system, there is no need to transmit userBankName) | String* |
orderId | The customer's transaction ID code needs to be managed. “orderId” will be returned when the system receives a balance change (with transaction information that matches the transaction created with the QR code). Maximum 13 characters. | String (Optional) |
terminalCode | Point of sale code | String (Optional) |
sign | Signature | String (Optional) |
Output:
Parameter | Value | Type |
bankCode | Bank code. List of bankCode: (Document page 14 or Link here) | String |
bankName | Bank name | String |
bankAccount | Bank account generates VietQR code | String |
userBankName | Account name | String |
amount | Amount of money | String |
content | Money transfer content | String |
qrCode | String QR Code snippet to display VietQR code | String |
qrLink | VietQR payment link. Customers can use this displayed link to pay. | String |
terminalCode | Point of sale code | String |
2.3. Format APIs Callback
A. Environment: UAT
說明：合作夥伴需要根據VietQR格式建立API才能接收有關帳戶餘額波動的資訊。
VietQR將主動呼叫合作夥伴的API回呼來更新此資訊。
注意：目前，VietQR僅支援連接MBBank和BIDV銀行接收餘額波動資訊。
2.3.1. API Get Token from Partner
Requests from Partners:
合作夥伴需要向VietQR提供以下資訊進行註冊：
Basic Authen Key: Includes username and password.
IP Address + Port: IP address and connection port.
URL: URL path for the API.
Format API:
URL Format: [IP_Address]:[PORT]/…/api/token_generate
Phương thức: POST
Accuracy: Basic Authentication
Headers:
Parameter | Value |
Authorization | Basic [username]:[password] |
Content-Type | Application/json |
Output:
Parameter | Value | Type |
access_token | The token is returned to call the author's POST transaction-sync API | String |
token_type | Default: Bearer Token | String |
expires_in | Token expiration time. Default is 59 seconds | String |
2.3.2. API Transaction Sync (Receive Balance Change) from Counterparty:
Requests from Partners:
合作夥伴需要向VietQR提供以下資訊以建立連線：
IP Address + Port: IP address and connection port.
URL: URL path for the API.
Format API:
URL Format: [IP_Address]:[PORT]/…/bank/api/transaction-sync
Phương thức: POST
Accuracy: Use Bearer Token.
Headers:
Parameter | Value |
Authorization | Bearer Token |
Content-Type | Application/json |
Input:
Parameter | Value | Type |
transactionid | ID of transaction | String |
transactiontime | Tansaction record time | Long |
referencenumber | Reference number of the returned bank. | String |
amount | Amount of money | int |
content | Transfer content | String |
bankaccount | 銀行帳號 | String |
transType | 借記/貸記交易（價值：D/C） | String |
orderId | 客戶發票代碼 | String |
Sample input:
Output:
Parameter | Value | Type |
error | Error flag: true/false. If an error occurs on the other side, please return true. | boolean |
errorReason | 錯誤代碼 | String |
toastMessage | 錯誤描述 | String |
[“object”][“reftransactionid”] | Counterparty management reference ID | String |
Sample output:
2.4 API Check Callback Transaction
Test Environment (UAT)
URL API: http://112.78.1.220:8084/vqr/bank/api/test/transaction-callback
Method: POST
Detailed Description
- This API is designed to test the callback connection from the VietQR system to the partner's system. This is part of the testing and simulation process.
運作:
Transaction Assumptions:
在此測試環境中，API假設交易已完成並結算.
需要提供的信息:
銀行帳戶資訊（bankAccount）：客戶需要將註冊銀行帳戶的準確資訊傳輸到測試環境.
交易訊息:
交易金額
交易內容
交易類型 (transType)
交易確認: 當收到準確的資訊時，VietQR系統將在測試環境中確認交易並將其標記為「已付款」。.
Headers:
Parameter | Value |
Authorization | Bearer Token lấy từ API get Token |
Content-Type | Application/json |
Input:
Parameter | Value | Type |
bankAccount | 銀行帳戶 | String |
content | 交易內容 註：此交易內容由VietQR系統格式化。 從 VIETQR 程式碼產生 API 返回 | String |
amount | 金額 | String |
transType | 借記/貸記交易（價值：D/C） | String |
Output:
Parameter | Value | Type |
status | “SUCCESS”: 成功 “FAILED”: 發生錯誤 | String |
Message | 傳回錯誤代碼 ( + 錯誤描述) khi status = “FAILED” | String |
錯誤代碼表:
Error Code | 描述 |
E46 | 非法的Request Body |
E74 | 無效的token |
E75 | API callback test service is not available |
E76 | 該客戶未在系統中註冊 |
E77 | 銀行帳戶與客戶資訊不符 |
002 | 金額無效 |
009 | 無效內容 |
010 | 帳號無效 |
003 | transType 無效 |
E05 | 未知錯誤（此錯誤代碼通常與錯誤描述一起傳回） |
2.6 API Check Transaction:
Môi trường: UAT
Method: POST
Accuracy: Bearer Token (從取得Token API傳回的Token)
描述: API使用orderId或referenceNumber檢查交易狀態。
Input/Request Body:
Field | Value | Type |
bankAccount | 銀行帳號 | String* |
type | 檢查分類 - 0: 透過orderId查詢 - 1: 透過referenceNumber 查詢 | int* |
value | 檢查值（orderId或referenceNumber值） | String* |
checkSum | MD5編碼字串（bankAccount + accessKey） *註：accessKey為客戶端呼叫取得Token介面時提供的使用者名. | String* |
Output:
成功的情況: LIST JSON
Field | Value | Type |
amount | 金額 | long |
transType | “C”: GD 信用 “D”: GD 借方 | String |
orderId | 發票代碼 | String |
referenceNumber | 交易代碼 | String |
timeCreated | 建立交易時間 | long |
timePaid | 付款時間 | long |
status | 交易狀態: 0：等待付款 1：成功 2：取消 | int |
type | 交易類型： 0：使用 VietQR 程式碼建立的 GD 2：其他教育 | int |
content | Transfer content | String |
錯誤的情況:
Field | Value | Type |
status | FAILED | String |
message | 傳回錯誤代碼 | String |
Bảng mã lỗi:
Error Code | Mô tả |
E46 | 請求正文無效 |
E05 | 未知錯誤 |
E74 | Bearer Token 無效 |
E77 | 銀行帳號不屬於商家 |
E39 | 校驗和無效 |
E95 | 交易類型（請求正文中的“type”欄位）無效 |
E96 | 沒有找到對應的交易 |
進階API :
2.5 - 提供付款金額語音通知的API（Get Voice for Transaction API）
環境: UAT
URL: http://112.78.1.220:8084/vqr/api/voice/transaction
Phương Thức (Method): POST
描述:
該API旨在提供帳戶餘額波動的語音讀取。 使用時，API 將返回錄音作為連結。 客戶可以使用此連結收聽有關其餘額波動的資訊。
- 輸入：Input:
Parameter | Value | Type |
userId | 系統中的使用者識別碼。 測試數據：“62ad476d-3b6b-4926-9890-fa6a20144f7f” | String |
amount | 金錢金額 | String |
type | 預設值為 0 | int |
transactionId | 系統中的交易識別碼。 測試數據：「」留空 | String |
Output:
Parameter | Value | Type |
status | “SUCCESS”: 成功 “FAILED”: 發生錯誤 | String |
Message | Nếu status = SUCCESS: 返回語音連結 Nếu status = FAILED: 傳回錯誤代碼 | String |
- 錯誤代碼表:
Error Code | Mô tả |
E46 | 非法的Request Body |
E05 | 未知錯誤 |
E67 | 未找到用戶資訊 |
E58 | 類型錯誤。 預設類型 = 0。 |
注意👍
● 透過IP:連接埠連線：當合作夥伴以 IP:PORT 的形式提供連線資訊時，不需要 SSL（安全通訊端層）相關資訊。
● 透過網域連接：如果透過網域連接，則需要有 SSL 憑證。 需確保SSL憑證配置正確，以確保通訊過程中的安全保障。
● 不能在本機上測試：無法在本機上執行測試。 應使用其他合適的測試環境進行測試和評估。
● 請求中的資料字段:
只需填寫您在請求中推送的資料欄位即可。 對於未推送的字段，請將值保留為空字串 ("")。
Đáp đáp :
5 – 上線準備說明
恭喜您成功完成測試階段！ 現在，我們將準備好進入上線階段。 以下是必要的支援資訊和資源：
5.1 - 完整的 VIetQR VN 品牌標識 🙂
5.1.1 - 品牌指導文件 :
Thương hiệu và chuẩn nghiêm thu VietQR - Google Tài liệu
5.1.2 -確認品牌並準備上線（線上）：
(Technical representatives of both sides confirm the degree)
聯繫上線:
Email Hỗ Trợ: sales@vietqr.vn
Hotline Hỗ Trợ: 19006234
Website Thông Tin: VIETQR.VN | VIETQR.COM | VIETQR.ORG
其他資源和支持:
常見問題、論壇、教學：這些資源將幫助您回答問題，並在準備和實施上線期間提供額外支援。
參考:
測試程式碼和測試樣本:
術語和定義：
銀行代碼表：
No | Bank Code | Bank Name |
1 | ABB | Ngân hàng TMCP An Bình |
2 | ACB | Ngân hàng TMCP Á Châu |
3 | BAB | Ngân hàng TMCP Bắc Á |
4 | BIDV | Ngân hàng TMCP Đầu tư và Phát triển Việt Nam |
5 | BVB | Ngân hàng TMCP Bảo Việt |
6 | CAKE | TMCP Việt Nam Thịnh Vượng - Ngân hàng số CAKE by VPBank |
7 | CBB | Ngân hàng Thương mại TNHH MTV Xây dựng Việt Nam |
8 | CIMB | Ngân hàng TNHH MTV CIMB Việt Nam |
9 | COOPBANK | Ngân hàng Hợp tác xã Việt Nam |
10 | DBS | DBS Bank Ltd - Chi nhánh Thành phố Hồ Chí Minh |
11 | DOB | Ngân hàng TMCP Đông Á |
12 | EIB | Ngân hàng TMCP Xuất Nhập khẩu Việt Nam |
13 | GPB | Ngân hàng Thương mại TNHH MTV Dầu Khí Toàn Cầu |
14 | HDB | Ngân hàng TMCP Phát triển Thành phố Hồ Chí Minh |
15 | HLBVN | Ngân hàng TNHH MTV Hong Leong Việt Nam |
16 | HSBC | Ngân hàng TNHH MTV HSBC (Việt Nam) |
17 | IBK - HCM | Ngân hàng Công nghiệp Hàn Quốc - Chi nhánh TP. Hồ Chí Minh |
18 | IBK - HN | Ngân hàng Công nghiệp Hàn Quốc - Chi nhánh Hà Nội |
19 | ICB | Ngân hàng TMCP Công thương Việt Nam |
20 | IVB | Ngân hàng TNHH Indovina |
21 | KBank | Ngân hàng Đại chúng TNHH Kasikornbank |
22 | KBHCM | Ngân hàng Kookmin - Chi nhánh Thành phố Hồ Chí Minh |
23 | KBHN | Ngân hàng Kookmin - Chi nhánh Hà Nội |
24 | KLB | Ngân hàng TMCP Kiên Long |
25 | LPB | Ngân hàng TMCP Bưu Điện Liên Việt |
26 | MB | Ngân hàng TMCP Quân đội |
27 | MSB | Ngân hàng TMCP Hàng Hải |
28 | NAB | Ngân hàng TMCP Nam Á |
29 | NCB | Ngân hàng TMCP Quốc Dân |
30 | NHB HN | Ngân hàng Nonghyup - Chi nhánh Hà Nội |
31 | OCB | Ngân hàng TMCP Phương Đông |
32 | Oceanbank | Ngân hàng Thương mại TNHH MTV Đại Dương |
33 | PBVN | Ngân hàng TNHH MTV Public Việt Nam |
34 | PGB | Ngân hàng TMCP Xăng dầu Petrolimex |
35 | PVCB | Ngân hàng TMCP Đại Chúng Việt Nam |
36 | SCB | Ngân hàng TMCP Sài Gòn |
37 | SCVN | Ngân hàng TNHH MTV Standard Chartered Bank Việt Nam |
38 | SEAB | Ngân hàng TMCP Đông Nam Á |
39 | SGICB | Ngân hàng TMCP Sài Gòn Công Thương |
40 | SHB | Ngân hàng TMCP Sài Gòn - Hà Nội |
41 | SHBVN | Ngân hàng TNHH MTV Shinhan Việt Nam |
42 | STB | Ngân hàng TMCP Sài Gòn Thương Tín |
43 | TCB | Ngân hàng TMCP Kỹ thương Việt Nam |
44 | TIMO | Ngân hàng số Timo by Ban Viet Bank (Timo by Ban Viet Bank) |
45 | TPB | Ngân hàng TMCP Tiên Phong |
46 | Ubank | TMCP Việt Nam Thịnh Vượng - Ngân hàng số Ubank by VPBank |
47 | UOB | Ngân hàng United Overseas - Chi nhánh TP. Hồ Chí Minh |
48 | VAB | Ngân hàng TMCP Việt Á |
49 | VBA | Ngân hàng Nông nghiệp và Phát triển Nông thôn Việt Nam |
50 | VCB | Ngân hàng TMCP Ngoại Thương Việt Nam |
51 | VCCB | Ngân hàng TMCP Bản Việt |
52 | VIB | Ngân hàng TMCP Quốc tế Việt Nam |
53 | VIETBANK | Ngân hàng TMCP Việt Nam Thương Tín |
54 | VNPTMONEY | Trung tâm dịch vụ tài chính số VNPT- Chi nhánh Tổng công ty truyền thông (VNPT Fintech) |
55 | VPB | Ngân hàng TMCP Việt Nam Thịnh Vượng |
56 | VRB | Ngân hàng Liên doanh Việt - Nga |
57 | VTLMONEY | Tổng Công ty Dịch vụ số Viettel - Chi nhánh tập đoàn công nghiệp viễn thông Quân Đội |
58 | WVN | Ngân hàng TNHH MTV Woori Việt Nam |
DANH SÁCH APP VÍ ĐIỆN TỬ QUÉT CHẤP NHẬN THANH TOÁN MÃ VIETQR | ||
No | Bank Code | APP |
1 | MOMO | Ví điện tử Momo |
2 | VNPAY | Ví điện tử Vnpay |
3 | .... | Còn nhiều tổ chức khác,Vietqr sẽ cập nhật đầy đủ sau |
Last updated
