Cashback Integration Document for UAT - WebView - V1

1. Introduction

API Version: 1.1 (202303)

Updated At: 01 Mar 2023 Document Language: English

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

  • Định danh user trên hệ thống ATCashback

• Cách thực hiện

  • Đối tác sẽ mở 1 Webview trong ứng dụng của đối tác để mở tính năng mua sắm hoàn tiền

  • Cấu trúc của URL khi mở như sau:

    https://{rool_url}?token={partner_user_token}

    Vi dụ: url = https://atcashback.com?token=abcde123456

    • Giải thích

      • rool_url: Sẽ được cung cấp khi tích hợp

      • partner_user_token: Token định danh user trên hệ thống đối tác. Hệ thống ATCashback sẽ dùng token này để gọi qua hệ thống đối tác xác thực thông tin user + lưu lại một số thống để sử dụng cho các tính năng liên quan như Gửi notification, Gửi lệnh rút tiền về tài khoản bank

• Cách xác thực user

  • Bước 1: Đối tác cung cấp partner_user_token trên url khi mở webview mua sắm hoàn tiền

  • Bước 2: webview đọc thông tin token và gửi thông tin lên hệ thống server của ATCashback

  • Bước 3: Hệ thống Server ATCashback sẽ sử dụng token từ webview gửi lên, gọi qua hệ thống đối tác để xác minh token

  • Bước 4: Hệ thống đối tác xác thực token tử hệ thông ATCashback gửi qua

    • Token đúng:

      • Trả 1 số thông tin của User trên hệ thống đối tác về cho hệ thống ATCashback để định danh như:

        • Tên user // Để hiển thị lên phần Profile của webview

        • Mã định danh // Mỗi user cố định 1 mã định danh khác nhau, mã này để dùng để định danh user giữa 2 hệ thống đối tác và atCashback

        • Và một số thông khác // Các thông tin này phụ thuộc vào chính sách của từng đối tác

    • Token không đúng:

      • Trả lỗi về người dùng không xác định → Webview chuyển sang màn hình lỗi.

  • Bước 5:

    • Sau khi có thông tin user, hệ thông ATCashback sẽ lưu lại và cho phép user thao tác các tính năng trên webview

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

  • Partner user token truyền vào URL khi mở webview mua sắm hoàn tiền

  • Bộ API xác thực user để hệ thống ATCashback gọi qua xác thực user và lấy các thông tin cần thiết để thực hiện các tính năng trên webview

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