6.1. Tích hợp Webhook

Tích hợp WebHooks để Tingee bắn thông tin giao dịch đến ứng dụng bán hàng của bạn. Mỗi khi phát sinh giao dịch, Tingee sẽ bắn WebHooks, ứng dụng bán hàng của bạn sẽ biết khách hàng đã thanh toán

Tích hợp Webhook

Bước 1: Khách hàng đăng ký tài khoản Tingee tại app.tingee.vn, thêm cửa hàng và liên kết tài khoản ngân hàng cho cửa hàng - Chi tiết xem tại mục 1.2 và 1.3

Bước 2: Từ Trang chủ Tingee chọn Avatar -> Developers

Bước 3: Khách hàng chọn Thêm Url và dán URL Webhook cần nhận thông tin biến động số dư vào trường tương ứng sau đó chọn Lưu

Bước 4: Kiểm tra tính toàn vẹn dữ liệu từ Tingee gửi qua Webhook đã cập nhật như sau

• Headers trả về có 2 thông số: x-signature và x-request-timestamp

Lưu ý: Ở một số ngôn ngữ 2 thông số x-signature và x-request-timestamp có thể bị convert thành tên khác. VD: Ở ngôn ngữ PHP 2 thông số đã bị biến đổi thành HTTP_X_SIGNATURE và HTTP_X_REQUEST_TIMESTAMP

• Body trả về là 1 Object với nhiều trường thông tin:

{
  "clientId": string, //Id merchant
  "transactionCode": string, //Mã giao dịch
  "amount": number, //Số tiền
  "content": string, //Nội dung
  "bank": string, //Ngân hàng
  "accountNumber": string, //Số tài khoản
  "vaAccountNumber": string, //Số tài khoản VA(ảo)
  "transactionDate": string "yyyyMMddHHmmss" //Thời gian giao dịch
  "additionalData": list { name: string, value: string }[] //Thông tin còn lại trả về
}

• Quy tắc kiểm tra tính toàn vẹn dữ liệu: Chuỗi giá trị cần hash = {x-request-timestamp}:{response body convert về string}

• Sau đó thực hiện mã hóa chuỗi bên trên với giải thuật: HMAC SHA512, dùng Secret key là Secret token được tingee cung cấp sau khi có tài khoản trên Tingee.

• Chuỗi mã hóa được sinh nếu giống thông số x-signature thì được coi là hợp lệ

• Sau khi ứng dụng đối tác xử lý kết quả thì trả về response cho tingee như sau:

{
code: string,
message: string
}

• Với code = '00' - Thành công

• Hoặc code = '02' - Giao dịch đã được cập nhật thành công

• Hoặc code = '09' - Chữ ký không hợp lệ

• Hoặc code = 'xx' (mã lỗi khác)

Lưu ý:

• Trả về khác 00 hoặc 02 sẽ retry 5 lần mỗi lần 5 phút

• Retry khi gọi API timeout quá 10s tối đa năm lần, mỗi lần cách nhau 1 phút