Cashback Integration Document for UAT - WebView - V2

1. Introduction

API Version: 1.1 (202303)

Updated At: 01 Mar 2023 Document Language: Vietnamese

Tài liệu này sử dụng chuyên dành cho các ngân hàng, tổ chức tài chính tích hợp hệ thống mua sắm hoàn tiền AT Cashback để làm giàu tính năng sản phẩm, kích thích khách hàng tương tác, tăng lưu lượng giao dịch của khách hàng trên hệ thống.

2. Hướng dẫn tích hợp

Nội dung tích hợp gồm 4 hạng mục sau:

• Tạo url để mở webview

• Lắng nghe thông tin từ Webview để hỗ trợ mở link affiliate

• Cơ chế gửi notification

• Cơ chế tạo lệnh rút tiền

2.1. Tạo url để mở webview

Mục đích: Ðây là API để phía hệ thống AT ghi nhận thông tin user của đối tác, và đối tác lấy thông tin URL để thực hiện mở webview trên ứng dụng của đối tác

• Input:

  • Thông tin định danh của user

    • userId : ID định danh của user trên 2 hệ thống đối tác và AT

    • Lưu ý:

      • userId là unique và không bị thay đổi

      • userId được sử dụng để định danh user và thực hiện các giao tiếp khác như gửi notification đến user, user tạo yêu cầu rút tiền về tài khoản đối tác

      • userName : Tên của user trên hệ thống VPBank

• Output:

  • url: Ðây là url để mở webview của tính năng mua sắm hoàn tiền

  • url sẽ có dạng: https://webview-partner.devatcashback.com?token=....

API

• Method: POST

• Path: /api/user/generate-auth-url

• Header:

Key	Value
Checksum	SHA256( request body + timestamp + checksum key ) Checksum key provided by AT
Timestamp	Timestamp of request in seconds

• Body

// { "userId": "partner_user_id", "userName": "partner_user_name" }

• Response

200

// { "code": 1, "message": "Thành công", "data": { "url":
"https://...." } }

400

// { "code": xx, "message": "error message", "data": {} }

Lưu ý

• userToken

  • Hết hạn sau 10 phút // Sau khi partner nhận được url thì cần mở webview ngay

  • Chỉ sử dụng 1 lần // partner không sử dụng lại url, mỗi lần user click vào tính năng mua sắm hoàn tiền thì cần partner gọi qua để lấy url mới Key Value Checksum SHA256( request body + timestamp + checksum key )

• Checksum key provided by AT Timestamp Timestamp of request in seconds

  • Example checksum

    • Body

    //{"userId":"123123","userName":"Sinh"}

    • Timestamp: 1686803422

    • → Checksum = sha256({"userId":"123123","userName":"Sinh"}16868034221msf5mv1jtgc t7t1fijwfdk300qzp5rg) = 2013702f77d963949028f96f3175a7188489a55e545fd7cceb4ba3eb0c5b 78ac

2.2. Lắng nghe thông tin từ Webview để hỗ trợ mở link affiliate

• Mục đích:

  • Tính năng mua sắm hoàn tiền cần điều hướng qua các ứng dụng khác để thực hiện việc mua sắm như Shopee, Lazada, Tiki, …

  • Để có thể mở được các ứng dụng khác (Mở ra trình duyệt của hệ điều hành) thì cần ứng dụng của đối tác trên thiết bị di động hỗ trợ việc mở khi nhận được tín hiệu từ webview của ATCashback

• Các thực hiện

  • Khi phát sinh 1 yêu cầu mở thì webview sẽ gửi 1 thông điệp ra cho mobile

    • name: jsMessageHandler

    • body: String

      • Được convert từ object

        • Call hotline //{"type":"open_tel_link","value":"1900638089"}

          • type: open_tel_link

          • value: 1900638089

        • Open affiliate link //{"type":"open_affiliate_link","value":"https://go.isclix.com/deep_link/..."}

          • type: open_affiliate_link

          • value: affiliate link

    • Code example

      /**
       * Trigger native call hotline
       *
       */
      const callHotline = () => {
        sendMessage({
          type: 'open_tel_link',
          value: AppConst.phoneContact,
        });
      };
      
      /**
       * Trigger native open aff link
       *
       * @param url
       */
      const openAffLink = (url: string) => {
        if (!url) {
          return;
        }
        sendMessage({
          type: 'open_affiliate_link',
          value: url,
        });
      };
      
      /**
       * Send message to native
       *
       * @param data
       */
      const sendMessage = (data: any) => {
        data = JSON.stringify(data);
        // ios
        window.webkit?.messageHandlers?.jsMessageHandler?.postMessage(data);
        // android
        global?.JSBridge?.sendMessage(data);
        // react native
        window?.postMessage(data, '*');
      };

  • Mobile lắng nghe thông điệp đó và lấy thông tin mở tương ứng

    • IOS - Swift

      let config = WKWebViewConfiguration()
      config.userContentController.add(self, name: "jsMessageHandler")
      let web = WKWebView(frame: CGRect.zero, configuration: config)
      
      extension ViewController: WKScriptMessageHandler {
          func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
              if message.name == "jsMessageHandler" {
                  guard let ms = message.body as? String else { return }
                  guard let data = ms.data(using: .utf8) else { return }
                  do {
                      if let json = try JSONSerialization.jsonObject(with: data, options : .allowFragments) as? [String:String] {
                         guard let type = json["type"], let value = json["value"] else { return }
                         var url: URL?
                         if type == "open_affiliate_link", let url_ = URL(string: value) {
                             url = url_
                         }
                         if type == "open_tel_link", let url_ = URL(string: "tel:\\(value)") {
                             url = url_
                         }
      
                         guard url != nil else { return }
                         if UIApplication.shared.canOpenURL(url!) {
                             UIApplication.shared.open(url!, options: [:], completionHandler: nil)
                         }
                      } else {
                          print("bad json")
                      }
                  } catch let error as NSError {
                      print(error)
                  }
              }
          }
      }

    • Android - Kotlin

      class JSBridge(val context: Context) {
              @JavascriptInterface
              fun sendMessage(message: String) {
                  try {
                      JSONObject(message).apply {
                          when (opt("type")) {
                              "open_tel_link" -> {
                                  context.startActivity(Intent(Intent.ACTION_VIEW).apply {
                                      data = Uri.parse("tel:${opt("value")}")
                                  })
                              }
                              "open_affiliate_link" -> {
                                  context.startActivity(Intent(Intent.ACTION_VIEW).apply {
                                      data = Uri.parse("${opt("value")}")
                                  })
                              }
                          }
                      }
                  } catch (e: Exception) {
                      Toast.makeText(context, e.message, Toast.LENGTH_LONG).show()
                  }
              }
          }

• Tóm lại, đối tác cần chuẩn bị

  • Mobile hỗ trợ việc lắng nghe và mở ra trình duyệt tương ứng theo code hướng dẫn trên

2.3. Cơ chế gửi notification

• Mục đích

  • Khi trạng thái đơn hàng của user có sự thay đổi, hoặc các yêu cầu rút tiền của user có thay đổi trạng thái thì cần thông báo cho user

• Cách thực hiện

  • Bước 1:

    • Khi hệ thống ATCashback gọi qua xác thực user thì cần hệ thống đối tác trả thêm các thông tin đủ để hỗ trợ việc gửi notification

    • Hoặc có thể sử dụng mã định danh của User, và hệ thống đối tác dựa vào mã định danh của user để gửi notification về cho user

  • Bước 2:

    • Khi phát sinh nhu cần cần push notification đến user thì hệ thông ATCashback sẽ gọi qua hệ thống đối tác để yêu cầu push notification đến user

      • Lưu ý: Mỗi lần gửi qua đối tác, hệ thống ATCashback sẽ limit tối đa 1000 message cho 1 lần gửi.

• Nội dung notification

Status	Thời điểm gửi	Title	short content	Content
transaction_pending	Ngay khi hệ thống ghi nhận đơn hàng	Ghi nhận đơn hàng	Đơn hàng [#....] tại [Brand] đã được ghi nhận thành công.	Đơn hàng [#....] tại [Brand] đã được ghi nhận thành công. Thời gian hoàn tiền dự kiến từ 30-60 ngày kể từ ngày ghi nhận đơn hàng. Liên hệ Hotline: [...] để biết thêm thông tin chi tiết.
transaction_approved	Khi nhà cung cấp đối soát thành công và đồng ý thanh toán	Hoàn tiền thành công	Chúc mừng bạn đã nhận hoàn tiền [...đ] thành công cho đơn hàng [#...] trị giá [...đ] tại [Brand].	Chúc mừng bạn đã nhận hoàn tiền [...đ] thành công cho đơn hàng [#...] trị giá [...đ] tại [Brand]. Liên hệ Hotline: [...] để biết thêm thông tin chi tiết.
transaction_rejected	Khi nhà cung cấp từ chối đơn hàng / xác nhận đơn hàng bị hoàn/huỷ	Hoàn tiền không thành công	Đơn hàng [#....] trị giá [...đ] tại [Brand] của bạn vừa bị đối tác từ chối xử lý.	Đơn hàng [#....] trị giá [...đ] tại [Brand] của bạn vừa bị đối tác từ chối xử lý. Liên hệ Hotline: [...] để biết thêm thông tin chi tiết.
Withdrawl - success	Khi yêu cầu rút tiền được thực hiện thành công	Rút tiền thành công	Chúc mừng bạn đã rút thành công [...đ] về tài khoản MB Bank.	Chúc mừng bạn đã rút thành công [...đ] về tài khoản MB Bank. Mã giao dich [{transactionId}]. Liên hệ Hotline: [...] để biết thêm thông tin chi tiết.
Withdrawl - rejected	Khi yêu cầu rút tiền bị huỷ	Rút tiền không thành công	Rút tiền đã bị từ chối xử lý. Liên hệ Hotline: [...] để biết thêm thông tin chi tiết.	Rút tiền đã bị từ chối xử lý. Mã giao dich [{transactionId}]. Liên hệ Hotline: [...] để biết thêm thông tin chi tiết.
Withdrawl - pending	Khi yêu cầu rút tiền bị treo ở trạng thái đang xử lý (không nhận được phản hồi từ ngân hàng)	Yêu cầu rút tiền thành công	Yêu cầu rút tiền đang được MB Bank xử lý, bạn sẽ nhận được tiền về ngân hàng sau khi xử lý xong.	Yêu cầu rút tiền đang được MB Bank xử lý, bạn sẽ nhận được tiền về ngân hàng sau khi xử lý xong. Mã giao dich [{transactionId}]. Liên hệ Hotline: [...] để biết thêm thông tin chi tiết.

• Tóm lại, hệ thống đối tác cần chuẩn bị

  • Thông tin device của user, hoặc có thể sử dụng Mã định danh của user (Tùy vào solution của từng đối tác)

  • Bộ API gửi notification, để hệ thống ATCashback sử dụng khi cần gửi notification đến user

2.4. Cơ chế tạo lệnh rút tiền

• Mục đích

  • Khi user tích lũy đủ điều kiện rút tiền thì hệ thống ATCashback cho phép user chuyển số tiền này về số dư của họ trên hệ thông đối tác

• Cách thực hiện

  • Bước 1:

    • Hệ thống đối tác trả thêm 1 số thông tin của user đủ để hệ thống ATCashback có thể gọi được api chuyển tiền qua hệ thống đối tác

    • Hoặc có thể sử dụng mã định danh user để thực hiện api chuyển tiền

  • Bước 2:

    • Khi user phát sinh yêu cầu chuyển tiền, thì hệ thống ATCashback sẽ thực hiện gửi thông qua hệ thống đối tác để thực hiện chuyển tiền.

  • Bước 3:

    • Nếu api chuyển tiền thành công:

      • Lệch chuyển tiền trên hệ thống ATCashback sẽ ở trạng thái thành công và tiến hành gửi notification về cho user

    • Nếu api chuyển tiền không thành công:

      • Lệnh chuyển tiền trên hệ thống ATCashback sẽ ở trạng thái pending và chờ xử lý thủ công

• Tóm lại, hệ thống đối tác cần chuẩn bị

  • Thông tin tài khoản nhận của user, hoặc có thể sử dung Mã định danh của user (Tùy vào solution của từng đối tác)

  • Bộ API chuyển tiền để hệ thống ATCashback sử dụng khi có yêu cầu từ user trên hệ thống ATCashback

Hệ thống

• Mỗi đối tác sẽ được cung cấp

  • 1 trang CRM

  • 1 webview tích hợp trên ứng dụng (Mobile) của đối tác