Tài liệu này cung cấp hướng dẫn tổng quan và các thông tin kỹ thuật cần thiết để đối tác kết nối, tích hợp và sử dụng các dịch vụ API VietQR trên môi trường Production tại https://api.vietqr.org.

Thông qua bộ API VietQR, đối tác có thể tích hợp quy trình thanh toán QR vào hệ thống của mình, từ xác thực kết nối, tạo mã QR, quản lý điểm bán, nhận dữ liệu giao dịch, tra cứu giao dịch đến hoàn tiền. API Generate VietQR Code hỗ trợ các loại mã QR động, QR tĩnh và QR bán động, phù hợp với nhiều mô hình thanh toán và điểm bán khác nhau.

Tổng quan các nhóm API dịch vụ

Quy trình tích hợp tổng quát

Quy trình kết nối cơ bản gồm:

1. Xác thực → 2. Tạo QR → 3. Khách hàng thanh toán → 4. Nhận dữ liệu giao dịch → 5. Đối soát/tra cứu giao dịch → 6. Hoàn tiền khi cần thiết

Đối tác sử dụng API Get Token để lấy Bearer Token, sau đó sử dụng token này để gọi các API cần xác thực. Với dịch vụ hoàn tiền, VietQR sử dụng thêm secretKey và checkSum để tăng cường bảo mật cho yêu cầu API.

Mục đích của tài liệu

Tài liệu được xây dựng nhằm giúp đội ngũ kỹ thuật của đối tác:

• Nhanh chóng thiết lập kết nối với VietQR.

• Kiểm thử API trên môi trường Production.

• Tích hợp chức năng tạo và thanh toán bằng VietQR.

• Đồng bộ và xử lý dữ liệu giao dịch.

• Quản lý giao dịch theo từng cửa hàng/điểm bán.

• Tra cứu và đối soát giao dịch.

• Tích hợp chức năng hoàn tiền.

• Xử lý các trường hợp bất thường như QR hết hạn, callback lỗi hoặc giao dịch hoàn tiền thất bại.

1. Tài liệu hỗ trợ kết nối & giới thiệu sản phẩm

Khách hàng có thể tham khảo các kênh thông tin chính thức của VietQR:

• API VietQR: api.vietqr.vn — kiểm tra và thử nghiệm kết nối API.

• Tài liệu API: doc.vietqr.vn — tài liệu kỹ thuật và hướng dẫn tích hợp.

• Website VietQR: vietqr.com — thông tin về sản phẩm và giải pháp VietQR.

2. Thông tin cần cung cấp để cấu hình kết nối API

Để VietQR hỗ trợ cấu hình và kiểm tra kết nối, khách hàng vui lòng cung cấp các thông tin sau:

① URL kết nối

URL: ................................................

Địa chỉ API của hệ thống khách hàng dùng để trao đổi dữ liệu với VietQR.

② URL Path / Suffix

Path: ................................................

Đường dẫn mở rộng của API nếu hệ thống khách hàng có sử dụng.

Ví dụ:

/api/v1/payment
/api/v1/transaction

③ Cặp Key trao đổi dữ liệu

Username và Password được sử dụng làm thông tin xác thực trong quá trình trao đổi dữ liệu giữa hai hệ thống.

3. Quy trình tích hợp VietQR

BƯỚC 1 — Kiểm tra & Test API

Khách hàng thực hiện kiểm tra kết nối API theo tài liệu hướng dẫn tại:

api.vietqr.vn

Thực hiện lần lượt các API cần thiết và kiểm tra:

• Kết nối thành công.

• Xác thực Username/Password.

• Gửi nhận dữ liệu.

• Tạo giao dịch.

• Nhận kết quả giao dịch.

• Kiểm tra trạng thái thanh toán.

• Đối soát dữ liệu nếu có.

BƯỚC 2 — Hỗ trợ kỹ thuật trong quá trình tích hợp

Trong quá trình test và tích hợp, VietQR sẽ hỗ trợ kỹ thuật thông qua nhóm Zalo dành riêng cho dự án/khách hàng.

Nhóm hỗ trợ dùng để:

• Trao đổi thông số kỹ thuật.

• Kiểm tra request/response.

• Xử lý lỗi kết nối.

• Kiểm tra dữ liệu giao dịch.

• Hỗ trợ kiểm thử API.

• Xác nhận điều kiện GOLIVE.

BƯỚC 3 — GOLIVE dịch vụ

Sau khi quá trình test API hoàn tất và các chức năng đã được xác nhận hoạt động ổn định, khách hàng tiến hành GOLIVE.

Để sử dụng đầy đủ hệ sinh thái VietQR, khách hàng:

1. Cài đặt ứng dụng Tingo Pay VietQR

• iOS: App Store

• Android: Google Play

2. Đăng ký / đăng nhập tài khoản

3. Liên kết tài khoản ngân hàng

4. Khai báo thông tin sử dụng dịch vụ

5. Kích hoạt dịch vụ VietQR

Sau khi hoàn tất, hệ thống có thể bắt đầu sử dụng các chức năng VietQR theo phạm vi dịch vụ đã đăng ký.

4. Sơ đồ quy trình tích hợp

┌──────────────────────┐
│      KHÁCH HÀNG      │
│  Cung cấp thông tin  │
│     kết nối API      │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│    CẤU HÌNH API      │
│ URL + Path + Key     │
│ Username + Password  │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│       TEST API       │
│     api.vietqr.vn    │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│   HỖ TRỢ KỸ THUẬT    │
│      Nhóm Zalo       │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│    KIỂM TRA NGHIỆM   │
│         THU           │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│        GOLIVE        │
│     Kích hoạt dịch vụ│
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│   TINGO PAY VIETQR   │
│ Liên kết NH + Khai báo│
│      sử dụng dịch vụ │
└──────────────────────┘

Bộ thông tin tối thiểu cần chuẩn bị

API Endpoint: URL + Path
Authentication: Username + Password
Môi trường: TEST → UAT → GOLIVE
Kênh hỗ trợ: Nhóm Zalo VietQR
Ứng dụng vận hành: Tingo Pay VietQR

Cách trình bày này sẽ phù hợp hơn nếu dùng làm tài liệu onboarding cho khách hàng/API Partner, đồng thời dễ mở rộng sau này khi VietQR bổ sung thêm API Key, Webhook URL, IP Whitelist, Secret Key, Callback URL, Sandbox/Production.