🌀API VIETQR - Host2Host

API VIETQR - Server to Server

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ách hàng

TK/TKNH

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

Liên kết

Giao dịch

Thanh toán

BĐSD

Biến động số dư

Nghiệp vụ

2.1. Luồng nghiệp vụ

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

Đã liên kết TK MBBank hoặc TK BIDV trên hệ thống VietQR.

ĐTNT

KH đăng ký dịch vụ thanh toán bằng mã VietQR trên ĐTNT.

ĐTNT

VietQR

ĐTNT gọi API lấy mã QR xác thực định danh.
Input:
- key/domain/userId dùng để định danh KH trên ĐTNT.

VietQR

KH truy cập vào app VietQR và quét mã QR xác thực định danh.
VietQR kiểm tra thông tin QR xác thực định danh.
- Nếu QR xác thực định danh không khả dụng: VietQR báo lỗi.
- Nếu QR xác thực định danh khả dụng: KH truy cập vào form kích hoạt sử dụng dịch vụ/cập nhật thông tin sử dụng dịch vụ.

VietQR

KH nhập thông tin để kích hoạt và sử dụng dịch vụ thanh toán bằng mã VietQR trên ĐTNT.
Input:
- Thông tin TKNH đã liên kết.

VietQR

ĐTNT

VietQR kiểm tra thông tin hợp lệ của KH:
- Nếu thông tin hợp lệ: VietQR thông báo cho ĐTNT trạng thái kích hoạt/cập nhật thông tin thành công. ĐTNT hiển thị thông tin đã kích hoạt của KH trên hệ thống.
- Nếu thông tin không hợp lệ: VietQR hiển thị thông tin lỗi cho KH.

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

Đã liên kết TK MBBank hoặc TK BIDV trên hệ thống VietQR.
Đã kích hoạt thành công dịch vụ thanh toán mã VietQR trên ĐTNT.

ĐTNT

Tạo đơn hàng/giao dịch cần thanh toán trên hệ thống ĐTNT.

ĐTNT

VietQR

ĐTNT gửi yêu cầu tạo mã VietQR giao dịch.
VietQR trả về thông tin mã VietQR giao dịch.

ĐTNT

Khách hàng thực hiện thanh toán qua mã VietQR ĐTNT.

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: http://112.78.1.209:8084/vqr/api/tid/sync-certificate
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

Mã QR dùng để hiển thị đối với máy box QR mới được lưu dưới firmware

certificateId

String

certificateId (Dùng để kết nối websocket)

API Get User Information

URL: https://api.vietqr.org/vqr/api/tid/infomation/{boxCode}
Method: GET
Xác thực: Bearer.
Mô tả:
API dùng để xem chi tiết thông tin của má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 hàng được liên kết của KH

userBankName

String

Tên chủ TK ngân hàng được liên kết

bankCode

String

Mã của NH

bankShortName

String

Tên viết tắt của ngân hàng

registerPlatform

String

nền tảng đăng ký của KH

address

String

Địa chỉ KH đăng ký

qrCode

String

Mã QR Code hiển thị dùng để thanh toán

API Tạo mã VietQR

URL: http://112.78.1.209:8084/vqr/api/tid/generate-qr
Method: POST
Request Body:

Field

Type

Description

bankAccount

String

Số TK ngân hàng đã liên kết

bankName

String

Tên ngân hàng đã liên kết

bankShortName

String

Tên viết tắt của ngân hàng đã liên kết

userBankName

String

Tên chủ TK ngân hàng đã liên kết

note

String

Ghi chú giao dịch

amount

String

Số tiền gán trên giao dịch

content

String

Nội dung chuyển khoản gán trên giao dịch

imgId

String

Mã id hình ảnh của ngân hàng

qrCode

String

Mã QR Code của giao dịch QR động

transType

String

Loại giao dịch đến “C” hoặc đi “D”

bankCode

String

Mã code của ngân hàng

orderId

String

Mã giao dịch gán với giao dịch

terminalCode

String

Mã code cửa hàng để đối soá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 dùng để nhận BĐSD khi có giao dịch tới
Method: POST
Response:

Field

Type

Description

notificationType

String

Mã của notificationType ‘N05’: Mã code nhận biết BĐSD tới

notificationId

String

Mã định danh của thông báo lưu dưới hệ thống VietQR

transactionReceiveId

String

Mã định danh của giao dịch lưu dưới hệ thống VietQR

bankAccount

String

Số TK của TK nhận BĐSD

bankName

String

Tên TK ngân hàng của TK nhận BĐSD

bankCode

String

Mã code của TK ngân hàng của TK nhận BĐSD

bankId

String

Mã định danh của TK ngân hàng lưu dưới hệ thống

terminalName

String

Tên cửa hàng (Mặc định ‘’)

terminalCode

String

Mã code của cửa hàng (Mặc định ‘’)

rawTerminalCode

String

Mã code cửa hàng raw (Mặc định ‘’)

content

String

Nội dung chuyển khoản

orderId

String

Mã đơn hàng của giao dịch

referenceNumber

String

Mã code giao dịch của giao dịch

amount

String

Số tiền của giao dịch

timePaid

String

Thời gian thanh toán giao dịch

type

String

Loại giao dịch

time

String

Thời gian tạo giao dịch

refId

String

Mã định danh của giao dịch đánh dấu của ngân hàng

status

String

0: Chờ thanh toán

1: Thành công

2: Đã hủy

traceId

String

Mã trace của transaction

transType

String

C: Giao dịch đến

D: Giao dịch đi

urlLink

String

Mặc đị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: https://112.78.1.209:8084/webhook/sync-certificate )

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

PreviousHỏi đáp API NextEnglish version