API Tài liệu kỹ thuật

API - Tài liệu kỹ thuật kết nối Tạo mã VietQR và nhận Biến động số dư đối soát

Giới thiệu

Dịch vụ thanh toán bằng mã VietQR là dịch vụ cung ứng hạ tầng kỹ thuật để thực hiện việc kết nối, truyền dẫn và xử lý dữ liệu điện tử để thực hiện các giao dịch thanh toán bằng mã VietQR giữa các tổ chức cung ứng dịch vụ trung gian thanh toán, các ngân hàng, từ đó cho phép thực hiện các giao dịch thanh toán bằng mã VietQR tại các đơn vị chấp nhận thanh toán bằng cách sử dụng Ứng dụng thanh toán mã QR. ̣ ( Nguồn : https://napas.com.vn/dich-vu-thanh-toan-bang-ma-qr-182220812174214287.htm )

2.1. API Lấy Token

Môi trường: UAT

URL: http://112.78.1.220:8084/vqr/api/token_generate

Phương thức: POST

2.1.1 API get Token:

Môi trường: UAT
URL:
Method: POST
Authorization:

Parameter

Value

Type

Basic Authentication

Username

Lấy từ hệ thống khở tạo môi trường test

Password

Lấy từ hệ thống khở tạo môi trường test

Headers:

Parameter

Value

Authorization

Basic [username:password]

Content-Type

Application/json

Output:

Parameter

Value

Type

access_token

Token được trả về để gọi các APIs khác trong hệ thống

String

token_type

Mặc định: Bearer Token

String

expires_in

Thời gian Token hết hạn. Mặc định là 59 giây

String

2.2 API TẠO MÃ VIETQR :

Môi Trường Thử Nghiệm (UAT)
URL: http://112.78.1.220:8084/vqr/api/qr/generate-customer
Method: POST
Headers:

Parameter

Value

Authorization

Bearer Token lấy từ API get Token

Content-Type

Application/json

Input:

Parameter

Value

Type

bankAccount

Tài khoản ngân hàng tạo mã VietQR

String*

amount

Số tiền

Long/String*

content

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.

String*

bankCode

Mã ngân hàng. Danh sách bankCode: https://docs.google.com/spreadsheets/d/1073HBsF1thj4vKc2pTVKh73YAOFUKaySRa8_kSOEzJs/edit?usp=sharing

String*

transType

Giao dịch ghi nợ/có (giá trị: D/C). Mặc định là “C”.

String*

userBankName

Họ tên chủ tài khoản.

(Nếu TK đã liên kết với hệ thống VietQR thì không cần truyền userBankName)

String*

orderId

Mã ID giao dịch bên khách hàng 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). Tối đa 13 ký tự.

String (Optional)

terminalCode

Mã điểm bán

String (Optional)

sign

Chữ ký

String (Optional)

Output:

Parameter

Value

Type

bankCode

Mã ngân hàng. Danh sách bankCode: (Tài liệu trang 14 hoặc Link tại đây)

String

bankName

Tên ngân hàng

String

bankAccount

Tài khoản ngân hàng tạo mã VietQR

String

userBankName

Tên chủ tài khoản

String

amount

Số tiền

String

content

Nội dung chuyển tiền

String

qrCode

Đoạn mã QR Code dạng String để hiển thị mã VietQR

String

qrLink

Đường dẫn VietQR thanh toán. Khách hàng có thể sử dụng link hiển thị này để thanh toán.

String

terminalCode

Mã điểm bán

String

2.3. Format APIs Callback

A. Môi trường: UAT

Mô tả: Đối tác cần tạo các API theo format của VietQR để có thể nhận thông tin về biến động số dư tài khoản.

VietQR sẽ chủ động gọi API callback từ các đối tác để cập nhật thông tin này.

Lưu ý: Hiện tại, VietQR chỉ hỗ trợ kết nối với ngân hàng MBBank Và BIDV cho việc nhận thông tin biến động số dư.

2.3.1. API Get Token từ Phía Đối Tác

Yêu cầu từ Đối Tác:

Đối tác cần cung cấp thông tin sau cho VietQR để đăng ký:

Basic Authen Key: Bao gồm username và password.

IP Address + Port: Địa chỉ IP và cổng kết nối.

URL: Đường dẫn URL cho API.

Format API:

URL Format: [IP_Address]:[PORT]/…/api/token_generate

Phương thức: POST

Xác thực: Basic Authentication

Headers:

Parameter

Value

Authorization

Basic [username]:[password]

Content-Type

Application/json

Output:

Parameter

Value

Type

access_token

Token được trả về để gọi POST API transaction-sync của phía tối tác

String

token_type

Mặc định: Bearer Token

String

expires_in

Thời gian Token hết hạn. Mặc định là 59 giây

String

2.3.2. API Transaction Sync (Nhận Biến Động Số Dư) từ Phía Đối Tác:

Yêu cầu từ Đối Tác:

Đối tác cần cung cấp thông tin sau cho VietQR để thiết lập kết nối:

IP Address + Port: Địa chỉ IP và cổng kết nối.
- URL: Đường dẫn URL cho API.
Format API:
- URL Format:
  [IP_Address]:[PORT]/…/bank/api/transaction-sync
- Phương thức: POST
- Xác thực: Sử dụng Bearer Token.
Headers:

Parameter

Value

Authorization

Bearer Token

Content-Type

Application/json

Input:

Parameter

Value

Type

transactionid

ID của giao dịch

String

transactiontime

Thời gian ghi nhận giao dịch

Long

referencenumber

Mã reference number của ngân hàng trả về.

String

amount

Số tiền

int

content

Nội dung chuyển khoản

String

bankaccount

Số tài khoản ngân hàng

String

transType

Giao dịch ghi nợ/có (giá trị: D/C)

String

orderId

Mã hoá đơn của khách hàng

String

Sample input:
Output:

Parameter

Value

Type

error

Cờ báo lỗi: true/false. Nếu phía đối tác xảy ra lỗi, vui lòng trả về giá trị true.

boolean

errorReason

Mã lỗi

String

toastMessage

Mô tả lỗi

String

[“object”][“reftransactionid”]

ID tham chiếu quản lý bên đối tác

String

Sample output:

{
"error": false,
"errorReason": "000",
"toastMessage":
"object": {
"reftransactionid": "360f6fb1-07ad-40bb-ba5e-52e7b282baa7"
}
}

2.4 API Kiểm Tra Giao Dịch Callback

Môi Trường Thử Nghiệm (UAT)

URL API: http://112.78.1.220:8084/vqr/bank/api/test/transaction-callback
Phương Thức: POST

Mô Tả Chi Tiết

API này được thiết kế để kiểm tra kết nối callback từ hệ thống VietQR đến hệ thống của đối tác. Đây là một phần của quá trình thử nghiệm và giả lập.

Cách Thức Hoạt Động:

Giả Định Giao Dịch:

Trong môi trường thử nghiệm này, API giả định rằng một giao dịch đã được hoàn thành và thanh toán.

Thông Tin Cần Cung Cấp:

- Thông Tin Tài Khoản Ngân Hàng (bankAccount): Khách hàng cần truyền thông tin chính xác của tài khoản ngân hàng đã đăng ký với môi trường thử nghiệm.
- Thông Tin Giao Dịch:
  - Số Tiền Giao Dịch
  - Nội Dung Giao Dịch
  - Loại Giao Dịch (transType)
- Xác Nhận Giao Dịch: Khi nhận được thông tin chính xác, hệ thống VietQR sẽ xác nhận và đánh dấu giao dịch đó là “Đã Thanh Toán” trong môi trường thử nghiệm.
Headers:

Parameter

Value

Authorization

Bearer Token lấy từ API get Token

Content-Type

Application/json

Input:

Parameter

Value

Type

bankAccount

Tài khoản ngân hàng

String

content

Nội dung giao dịch Lưu ý: Nội dung giao dịch này là nội dung đã được format bởi hệ thống VietQR. Được trả về từ API TẠO MÃ VIETQR

String

amount

Số tiền

String

transType

Giao dịch ghi nợ/có (giá trị: D/C)

String

Output:

Parameter

Value

Type

status

“SUCCESS”: Thành công

“FAILED”: Có lỗi xảy ra

String

Message

Trả về mã lỗi ( + mô tả lỗi) khi status = “FAILED”

String

Bảng mã lỗi:

Error Code

Mô tả

E46

Request Body không hợp lệ

E74

Token không hợp lệ

E75

Dịch vụ test callback API không khả dụng

E76

Khách hàng chưa được đăng ký trong hệ thống

E77

TK ngân hàng không khớp với thông tin của khách hàng

002

Số tiền không hợp lệ

009

Nội dung không hợp lệ

010

Số tài khoản không hợp lệ

003

transType không hợp lệ

E05

Lỗi không xác định (Mã lỗi này thường trả về kèm theo mô tả lỗi)

2.5 API Check Transaction:

Môi trường: UAT
URL: http://112.78.1.220:8084/vqr/api/transactions/check-order
Method: POST
Xác thực: Bearer Token (Token trả về từ API get Token)
Mô tả: API check trạng thái giao dịch bằng orderId hoặc referenceNumber.
Input/Request Body:

Field

Value

Type

bankAccount

Số tài khoản ngân hàng

String*

type

Phân loại check: - 0: check bằng orderId

- 1: check bằng referenceNumber

int*

value

Giá trị check (giá trị orderId hoặc referenceNumber)

String*

checkSum

Chuỗi String mã hoá MD5 (bankAccount + accessKey) * Lưu ý: accessKey là username mà khách hàng được cung cấp để gọi API get Token.

String*

Output:
- Trường hợp thành công: LIST JSON

Field

Value

Type

amount

Số tiền

long

transType

“C”: GD ghi có “D”: GD ghi nợ

String

orderId

Mã hoá đơn

String

referenceNumber

Mã giao dịch

String

timeCreated

Thời gian tạo giao dịch

long

timePaid

Thời gian thanh toán

long

status

Trạng thái giao dịch:

0: Chờ thanh toán

1: Thành công

2: Đã huỷ

int

type

Loại giao dịch: 0: GD tạo bằng mã VietQR

2: GD khác

int

content

Nội dung chuyển khoản

String

Trường hợp không thành công:

Field

Value

Type

status

FAILED

String

message

Trả về mã lỗi

String

- Bảng mã lỗi:

Error Code

Mô tả

E46

Request Body không hợp lệ

E05

Lỗi không xác định

E74

Bearer Token không hợp lệ

E77

Số TK ngân hàng không trực thuộc merchant

E39

checkSum không hợp lệ

E95

Loại giao dịch (field “type” trong request body) không hợp lệ

E96

Không tìm thấy giao dịch tương ứng

API NÂNG CAO :

2.6 - API cấp voice thông báo số tiền thanh toán (API Get Voice for Transaction)

Môi trường: UAT
- URL: http://112.78.1.220:8084/vqr/api/voice/transaction
- Phương Thức (Method): POST
Mô Tả:

API này được thiết kế để cung cấp tính năng lấy giọng nói đọc các biến động số dư tài khoản. Khi sử dụng, API sẽ trả về một đoạn ghi âm giọng nói dưới dạng đường link. Khách hàng có thể sử dụng link này để nghe thông tin về biến động số dư của mình.

Input:

Parameter

Value

Type

userId

Mã định danh user trong hệ thống. Dữ liệu test: “62ad476d-3b6b-4926-9890-fa6a20144f7f”

String

amount

Số tiền

String

type

Mặc định là 0

int

transactionId

Mã định danh giao dịch trong hệ thống. Dữ liệu test: Để rỗng “”

String

Output:

Parameter

Value

Type

status

“SUCCESS”: Thành công

“FAILED”: Có lỗi xảy ra

String

Message

Nếu status = SUCCESS: Trả về đường link voice

Nếu status = FAILED: Trả về mã lỗi

String

Bảng mã lỗi:

Error Code

Mô tả

E46

Request Body không hợp lệ

E05

Lỗi không xác định

E67

Không tìm thấy thông tin user

E58

Sai type. Mặc định type = 0.

Trường Dữ Liệu Trong Yêu Cầu:

Chỉ cần điền thông tin vào những trường dữ liệu mà bạn đẩy (push) trong yêu cầu. Đối với các trường không được push, để giá trị là chuỗi rỗng ("").

Đáp đáp 👍

Format API
URL có format :

// [IP_Addres]:[port]/...../bank/api/transaction-sync

Tài Nguyên và Hỗ Trợ Bổ Sung:

FAQs, Diễn Đàn, Hướng Dẫn: Các nguồn thông tin này sẽ giúp quý khách giải đáp thắc mắc và hỗ trợ thêm trong quá trình chuẩn bị và triển khai Go-Live.

PreviousTài liệu VietQR API (Vn)NextKết nối môi trường test

Last updated 2 months ago