Phía đối tác: Setup API

Phía đối tác: Setup API:

I.1B. TOKEN:

Đị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) URL:

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

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

Output: GIẢI THÍCH: access_token: bearer token expires_in: 59s hiệu lực trong 59 giây

OUTPUT KHÁCH HÀNG PHẢI SET: {

"access_token": "eyJhbGciOiJIUzUxMiJ9.eyJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwidXNlciI6IlkzVnpkRzl0WlhJdGJtRjJhWFJ5WVdOckxYVnpaWEl5TXpVdyIsImlhdCI6MTcxMzY2OTU0OCwiZXhwIjoxNzEzNjY5NjA3fQ.eAm351aXb9Bk_zEmJagboSN_Qv3NVUIM185qp01Upmw3wkV40q8B8R3Qp1QL4w3_3lWPy-ozzxDLSKClDHxsFQ",

"token_type": "Bearer",

"expires_in": 59

}

I.2B. Transaction-sync

Đị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

URL: https://[domainkhách]/vqr/bank/api/transaction-sync AUTH : Bearer token (lấy từ API token)

Output trả lại VietQR sau khi nhận được thông tin thanh toán

OUTPUT TRẢ LẠI CHO VIETQR:

{

" 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

LƯU Ý: Việc bảo mật sẽ do 2 phía cùng thực hiện

II.CHI TIẾT THỰC HIỆN API PHÍA ĐỐI TÁC

1B. Đầu tiên phía đối tác thực hiện API lấy token “bearer” API 1B.

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

METHOD: POST

USER: VIETQR CUNG CẤP PASS: VIETQR CUNG CẤP

EXAMPLE:

OUTPUT: {

"token_type": "Bearer",

"expires_in": 59

}

Lưu ý: Đối tác cần setup trước API này và cung cấp cho VietQR để VietQR có thể lấy được mã Bearer làm định danh, sau đó cấp lại tài khoản cho đối tác thực hiện API

2B. Sau khi có được bearer token sử dụng bearer token để thực thi API tạo QR code (API 2B)

Giải thích: Khi có một đơn hàng, yêu cầu thanh toán thì đối tác thực hiện API này để tạo mã QR, mã QR được trả lại output sẽ là chuỗi String

Khách hàng sử dụng thư viện chuyển đổi từ String (text) thành hình ảnh QR code sau đó hiển thị ra cho người dùng thanh toán.

URL: http://112.78.1.220:8084/vqr/api/qr/generate-customer METHOD: POST

AUTH:

Bearer Token lấy từ API get Token (API 1B) Content-Type: Application/json (Định dạng dữ liệu trả về mặc định)

INPUT:

{

"bankAccount": "045416688",

"userBankName": "DO DANG DUNG",

"bankCode": "MB",

"amount": 10000,

"content": "19char",

"transType": "C",

"orderId": "13char",

"urlLink": "https://............./?orderid=123456",

"terminalcode": "",

"sign": ""

}

dòng 1 số tài khoản ngân hàng thụ hưởng

dòng 2 tên chủ tài khoản

dòng 3 bankcode mã ngân hàng

dòng 4 số tiền (long)

dòng 5 nội dung (không dấu, không kí tự đặc biệt, tối đa 19 kí tự)

dòng 6 trạng thái (C có + / D nợ -)

dòng 7 orderid bên đối tác tự sinh tối đa 13 kí tự

dòng 8 Urlink KH cung cấp url back lại sau khi thanh toán thành công 3s.

dòng 9 Terminalcode là mã định danh điểm bán được khởi tạo trên app vietqr

dòng 10 chữ kí (có thể bỏ qua)

Lưu ý: Tất cả đều phải truyền, nếu không có thông tin thì để rỗng ""

THÔNG TIN BIẾN/ ĐỊNH DẠNG

bankAccount : (String)

userBankName : (String)

bankCode :(String)

amount : (Long)

content: (String)

transType: (String)

orderId: (String)

urLlink: (String)

terminalcode: (String)

sign: (String)

OUT PUT VIETQR TRẢ: {

"bankCode": "MB",

"bankName": "Ngân hàng TMCP Quân đội",

"bankAccount": "045416688",

"userBankName": "DO DANG DUNG",

"amount": "10000",

"content": "VQR664712cff7 19char",

"qrCode": "00020101021138530010A0000007270123000697042201090454166880208QRIBFTTA53037045405100005802VN62240820VQR664712cff7 19char63042B39",

"imgId": "58b7190b-a294-4b14-968f-cd365593893e",

"existing": 1,

"transactionId": "",

"transactionRefId": "ZmFiZTU2NjQtMjZjZi00MTEzLWIwOWEtNTAyNWQwNmRiM2Y1",

"qrLink": "https://vietqr.vn/test/qr-generated?token=ZmFiZTU2NjQtMjZjZi00MTEzLWIwOWEtNTAyNWQwNmRiM2Y1",

"terminalCode": null

}

THÔNG TIN BIẾN/ ĐỊNH DẠNG - các biến có thông tin như trên: - khác:

+ Content: trường này trả ra sẽ đi kèm theo mã đối soát của VietQR VQR…………(khi sử dụng API test/transaction-callback thì yêu cầu nội dung của API QR trả về - output)

+ qrCode: trường này trả ra string, đối tác sử dụng để render mã QR

+ transactionId : là id giao dịch được VietQR ghi lại và thông báo cho đối tác để lưu trữ và đối soát (ở api transaction-sync sẽ đối tác sẽ làm căn cứ để trả lại retransactionId)

+ qrLink : là weblink thanh toán của vietqr. Hỗ trợ khách hang trong việc thanh toán mà không cần sử dụng đến việc tạo QR cho khách hang quét, VietQR sẽ làm thay điều đó (urLlink sẽ là đường dẫn mà đối tác muốn back lại sau khi khách hàng đã thanh toán thành công ở weblink vietqr 3 giây)

+ terminalcode : là mã định danh của cửa hang, chi nhánh, phân loại đối tác, phân loại giao dịch khi đối tác muốn phân loại khách hang có thể dung case này để thực hiện filter giao dịch

LƯU Ý: nội dung giới hạn không vượt quá 19 kí tự - ordered không vượt quá 13 kí tự - terminalcode đăng kí không vượt quá 20 kí tự

3B. THỰC HIỆN TEST API CALLBACK

ĐỊNH NGHĨA: Đối tác sẽ thực hiện API testcallback sau khi tạo mã QR thành công, API này được sử dụng để giả định giao dịch thành công và gửi về địa chỉ API mà đối tác đã cung cấp trước đó ở phần (I.)

Khi gửi các thông tin này, vietqr sẽ xử lí kiểm tra giao dịch có tồn tại trên hệ thống UAT của khách hàng hay không, sau đó gửi API 2A.

LUỒNG HOẠT ĐỘNG:

ĐỐI TÁC GỬI API TEST CALLBACK => URL TEST CALLBACK => VIETQR THỰC HIỆN KIỂM TRA THÔNG TIN INPUT CỦA ĐỐI TÁC => NẾU CÓ THỰC HIỆN LỆNH GỬI API VÀO URL CỦA ĐỐI TÁC THEO TÀI LIỆU API 2A(VIETQR THỰC HIỆN)=> ĐỐI TÁC TRẢ LẠI OUTPUT CHO VIETQR ĐỂ ĐÁNH DẤU XÁC NHẬN ĐÃ NHẬN ĐƯỢC THÔNG TIN GIAO DỊCH (CALLBACK)

URL: http://112.78.1.220:8084/vqr/bank/api/test/transaction-callback

AUTH: bearer token lấy từ API 1B

INPUT:

{

"bankAccount": "045416688",

"content": "CONTENT LẤY TỪ OUTPUT API 2B",

"amount": 10000,

"transType": "C"

}

LƯU Ý: content lấy từ API 2B

OUTPUT khi giao dịch đã được gửi thành công và nhận lại được kết quả của khách API 2B:

{

"status": "SUCCESS",

"Message": "",

}

OUTPUT khi giao dịch không thành công:

{

"status": "FAILED",

"message": "E77"

}

GIẢI THÍCH:

Lỗi được trả ra khi mà khách hàng setup api [I.2B. Transaction-sync] chưa đúng. VietQR thực hiện API 2A nhưng không thành công, thì output của API 2A chính là mã lỗi ["message": "E77"]

4B. Checkorder

Định nghĩa: Thực hiện khi đã nhận được thông tin giao dịch hoặc chưa nhận được thông tin giao dịch từ API 2A mà vietqr gửi đi. Ngay lúc này thực hiện API checkorder để tìm kiếm giao dịch, truy vấn giao dịch

Truy vấn giao dịch bằng orderid đã nhập khi tạo QR API 2B Hoặc truy vấn bằng referenceNumber mà khách hang cung cấp

Tại sao lại là

referenceNumber do khách hàng cung cấp?

Khi giao dịch xảy ra sẽ có 2 case: + nhận được giao dịch sẽ có cả orderid và referenceNumber. + Đối tác không nhận được giao dịch thì không có gì, chỉ dựa vào orderid mà đã tạo ở API 2B để truy vấn hoặc yêu cầu người chuyển cung cấp mã refrencenumber để thực hiện truy vấn.
Khi đối tác không nhận được thông tin giao dịch (callback) thường là do khách hang đã sửa đổi nội dung, số tiền khi thanh toán quét QR, dẫn đến QR đó không còn hiệu lực và biến thành giao dịch chuyển khoản thông thường, không còn là giao dịch được tạo ra bởi API nữa.

Thưc thi API

URL: http://112.78.1.220:8084/vqr/api/transactions/check-order

AUTH: Bearer lấy từ AOI 1B

INPUT:

{

"bankAccount": "045416688",

"type": 0,

"value": "orderId123456",

"checkSum": ""

}

GIẢI THÍCH CHI TIẾT

API này để khách hàng thực hiện kiểm tra giao dịch khi vượt quá thời gian nhận callback nhưng chưa thấy VietQR trả thông tin thanh toán,

Thì thực hiện API này. Mấu chốt ở

"orderId" khách hàng đã tạo QR.

Khi gửi orderid này thì khách hàng sẽ nhận được thông tin của giao dịch.

Nếu không thực hiện được thì yêu cầu người thanh toán cung cấp Refrenumber.

sau đó sử dụng API để kiểm tra xem giao dịch có tồn tại trên hệ thống VietQR hay không

input

{

"bankAccount": "045416688",

"type": 0,

"value": "orderId123456",

"checkSum": ""

}

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

Out put trả ra:

amount Số tiền long

transType (stirng)

“C”: GD ghi có

“D”: GD ghi nợ

orderId (stirng)

Mã hoá đơn

referenceNumber (stirng)

Mã giao dịch

III. VIETQR THỰC HIỆN API

ĐỊNH NGHĨA: VIETQR thực hiện api khi và chỉ khi nhận được callback từ ngân hàng về thông tin thanh toán qua API 2B khách hàng đã tạo

LUỒNG THỰC HIỆN: VietQR sẽ lấy token bearer của đối tác đã cung cấp => lấy bearer làm AUTH cho API truyền thông tin thanh toán (transaction-sync)

1A. Lấy token từ phía đối tác cung cấp theo I1B. Token

URL: https://[domainkhách]/ vqr/api/token_generate (do đối tác cung cấp)

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

Output: bearer token

OUTPUT vietqr nhận được: {

"token_type": "Bearer",

"expires_in": 59

}

2.A Gửi Transaction-sync (callback – thông tin giao dịch)

URL: https://[domainkhách]/vqr/bank/api/transaction-sync (đối tác cung cấp theo I.2B) AUTH : Bearer token (lấy từ API token)

INPUT (THÔNG TIN VIETQR GỬI)

{

"transactionid": "",

"transactiontime": 111,

"referencenumber": "1122",

"amount": 20000,

"content": "VQRfbf5db9a7c.test14",

"bankaccount": "045416688",

"transType": "C",

"orderId": "123456"

}

Khi đối tác nhận được thì phải set respon lại cho vietqr để đánh dấu là giao dịch đã thành công => vietqr đã gửi api đi => đối tác nhận thành công callback => vietqr đánh dấu giao dịch thành công. Phục vụ cho API 4B. checkorder

Output khách hàng phải set như mục [I.2B. Transaction-sync]

PreviousTạo Mã QR NextChú ý kết nối môi trường Test

Last updated 2 months ago