API GET TOKEN – VIETQR

TÀI LIỆU HƯỚNG DẪN TÍCH HỢP

API GET TOKEN – VIETQR

Tài liệu kỹ thuật dành cho đối tác tích hợp API

1. Mục đích

API Get Token được sử dụng để lấy Bearer Token phục vụ xác thực khi đối tác gọi các API dịch vụ VietQR. Đối tác sử dụng thông tin xác thực do VietQR cung cấp để gửi yêu cầu POST đến API token_generate.

2. Thông tin Endpoint

Lưu ý: Khi kiểm thử, sử dụng endpoint Dev/Sandbox. Khi hệ thống đã được nghiệm thu và triển khai chính thức, sử dụng endpoint Production.

3. Cơ chế xác thực

API sử dụng Basic Authentication. Giá trị Authorization được tạo từ chuỗi username:password và mã hóa Base64.

4. Request

4.1. HTTP Method

POST

4.2. Request Body

API Get Token không yêu cầu dữ liệu nghiệp vụ trong Request Body. Thông tin xác thực được truyền thông qua HTTP Header Authorization.

5. Response thành công

HTTP Status: 200 OK

{
"access_token": "bearer_token_cua_VietQR_cung_cap",
"token_type": "Bearer",
"expires_in": 300
}

6. Giải thích Response

7. Ví dụ gọi API bằng cURL

curl --location --request POST \
'https://dev.vietqr.org/vqr/api/token_generate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <BASE64_USERNAME_PASSWORD>'

8. Quy trình sử dụng Token

Đăng ký tích hợp và nhận thông tin username/password từ VietQR.

Gọi API Get Token bằng Basic Authentication.

Nhận access_token từ response.

Lưu token trong bộ nhớ an toàn của hệ thống đối tác.

Sử dụng token theo dạng Authorization: Bearer <access_token> khi gọi các API yêu cầu xác thực.

Khi token hết hạn sau khoảng 300 giây, gọi lại API Get Token để lấy token mới.

9. Xử lý lỗi

Khi API trả về lỗi, đối tác cần kiểm tra lần lượt thông tin xác thực, endpoint đang sử dụng, môi trường Test/Production và cấu trúc HTTP Request. Nếu username/password không chính xác hoặc không còn hiệu lực, cần liên hệ VietQR để được kiểm tra.

{
"status": "FAILED",
"message": "ma_loi_va_mo_ta_loi"
}

10. Lưu ý bảo mật

Username, password và access_token là thông tin nhạy cảm; không đưa vào mã nguồn công khai hoặc Git repository.

Không chia sẻ access_token qua email, chat hoặc log hệ thống nếu không cần thiết.

Chỉ sử dụng HTTPS khi kết nối tới API.

Không hard-code username/password trong ứng dụng frontend hoặc mobile client nếu có thể tránh; nên thực hiện gọi token từ backend.

Theo dõi thời gian expires_in để chủ động lấy token mới trước khi token hết hạn.

11. Câu hỏi thường gặp

API Get Token dùng để làm gì?

API dùng để cấp Bearer Token, phục vụ xác thực khi truy cập các API VietQR yêu cầu quyền truy cập.

Làm thế nào để gọi API?

Gửi HTTP POST đến endpoint token_generate và truyền username/password dưới dạng Basic Authentication trong header Authorization.

Token có thời hạn bao lâu?

Thời hạn mặc định là 300 giây, tương đương 5 phút.

Có thể dùng token Test cho Production không?

Không. Token phải được sử dụng đúng môi trường tương ứng. Token Sandbox/Dev dùng cho môi trường Test; Production dùng token được cấp cho môi trường Production.

Nếu gọi API bị lỗi thì xử lý thế nào?

Kiểm tra username/password, Base64 Authorization, endpoint, HTTPS, môi trường và log phản hồi. Nếu vẫn lỗi, liên hệ bộ phận hỗ trợ VietQR.

12. Tài liệu tham chiếu

Nguồn tài liệu chính thức: https://api.vietqr.vn/vi/api-vietqr-callback/goi-api-get-token

Tài liệu này được biên soạn lại theo nội dung API Get Token hiện có trên tài liệu VietQR, với mục tiêu thuận tiện cho việc gửi đối tác, triển khai và kiểm thử tích hợp.