Chuẩn bị

Việc đối tác cần làm là chuẩn bị trước URL UAT, PROD để cung cấp cho VietQR triển khai được nhanh chóng.

Các nội dung đối tác cần chuẩn bị

  • Tài khoản liên kết với APP VietQR

  • API TOKEN

  • API CALLBACK

Sau khi chuẩn bị đầy đủ VietQR sẽ khởi tạo môi trường Test cho khách và cung cấp lại USER và PASS để đối tác truy cập và thực hiện API

LIÊN KẾT TÀI KHOẢN VỚI APP VIETQR

  • Liên kết tài khoản với APP VietQR

API TOKEN

Định nghĩa:

  • Đối tác khởi tạo kết nối bảo mật với VietQR để VietQR có thể định danh đối tác.

  • Cả hai sẽ đều phải thực hiện Basic Auth

  • Sau khi lấy được bearertoken mỗi bên sẽ thực hiện api khác nhau, đối tác thực hiện API tạo QR và Test Callback, API check order. VietQR thực hiện gửi transaction-sync cho đối tác (bước này bảo mật phải dùng là bearer token. Lưu ý: token chỉ có giá trị mặc định 59 giây, nên khi xuất hiện lỗi 403 thì thực hiện lấy lại token mới.)

Luồng thực hiện:

Đối tác cần setup API:

Định nghĩa: đối tác khởi tạo url và tạo user để cho VietQR đăng nhập vào và lấy bearer để thực hiện API gửi transaction-sync (thông báo thanh toán thành công

Bắt đầu setup

URL:

https://[domainkhách]/vqr/api/token_generate

Chú ý: Đây là url mà VietQR sẽ dùng để lấy token

Authorization : BASIC

User: đối tác khởi tạo cho VietQR Pass: đối tác khởi tạo cho VietQR

Output:

Application/Json

{
    "access_token": "eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdGJtRjJhWFJ5WVdOckxYVnpaWEl5TXpVdyIsImlhdCI6MTcxNDAzNDM5NCwiZXhwIjoxNzE0MDM0NDUzfQ.A9rDkYqNuQmhf0Ei2C8xvZoIaBATRr8CnkbyyznwF-JqR6Ki_rIxT0dODzM3nFU0K01gqLVBHHeQQQ_wPUMA0g",
    "token_type": "Bearer",
    "expires_in": 59
}

GIẢI THÍCH:

  • access_token: bearer token

  • expires_in: 59s hiệu lực trong 59 giây

Lưu ý: Các feild là bắt buộc không thay đổi thông số trả về, chỉ thay đổi value access_token

API CALLBACK

Định nghĩa:

  • Đối tác setup url để nhận thông báo thanh toán thành công và thông tin của giao dịch. VietQR sẽ thực hiện lấy Bearer => truyền API transactionsync

  • Đối tác thực hiện trả output như bên dưới nhằm mục đích thông báo rằng đối tác đã nhận được đầy đủ thông tin giao dịch => vietqr sẽ đánh dấu giao dịch thành công trên hệ thống để phục vụ API Check-order

Luồng thực hiện:

Bắt đầu setup

URL

https://[domainkhách]/vqr/bank/api/transaction-sync

Chú ý: Đây sẽ là url mà VietQR sẽ gửi Callback transaction-sync thông báo giao dịch

AUTH : Bearer token (lấy từ API token mà VietQR thực hiện)

Example:

eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdGJtRjJhWFJ5WVdOckxYVnpaWEl5TXpVdyIsImlhdCI6MTcxNDAzNDM5NCwiZXhwIjoxNzE0MDM0NDUzfQ.A9rDkYqNuQmhf0Ei2C8xvZoIaBATRr8CnkbyyznwF-JqR6Ki_rIxT0dODzM3nFU0K01gqLVBHHeQQQ_wPUMA0g

Giả định VietQR sẽ gửi thanh toán đến cho đối tác với INPUT:

{
    "transactionid": "",
    "transactiontime": 111,
    "referencenumber": "1122",
    "amount": 20000,
    "content": "VQRfbf5db9a7c.test14",
    "bankaccount": "045416688",
    "transType": "C",
    "orderId": "123456"
}

Khi đối tác nhận được thông tin này hãy trả lại respon cho VietQR, để đánh dấu là giao dịch thành công.

OUTPUT

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

GIẢI THÍCH:

  • Error : lỗi (false là không có lỗi xảy ra/ true là có lỗi xảy ra)

  • errorReason: mã lỗi

  • object trạng thái lỗi (nội dung, vị trí lỗi/ không có thì trả lại reftransactionid tự sinh ra )

  • reftransactionid chuỗi string được khách hàng lưu trữ và trả lại thông tin cho VietQR để đối soát

Sau khi setup xong các API trên đối tác có thể tự thực hiện yêu cầu tạo môi trường TEST theo link bên dưới.

Sau đó báo nhân viên VietQR theo sđt 19006234 - Dũng 0332556499 để kích hoạt môi trường TEST

PreviousKết nối môi trường testNextLấy Token

Last updated