Tích hợp SDK Giao diện (Frontend Web)

Tingee cung cấp thư viện Web SDK (Frontend) giúp bạn nhúng trực tiếp giao diện liên kết ngân hàng vào website dưới dạng Popup (Modal) hoặc hiển thị Inline trực tiếp trên trang.

---

1. Nhúng thư viện SDK

Thêm thẻ <script> sau vào mã nguồn HTML trang web của bạn (ví dụ: index.html hoặc tệp template chính):

Môi trường UAT:

<script src="https://uat-bank-link.tingee.vn/js/tingee-bank-link.js"></script>

Môi trường Production:

<script src="https://bank-link.tingee.vn/js/tingee-bank-link.js"></script>

---

2. Cấu hình & Lắng nghe sự kiện (Setup)

Trước khi mở màn hình liên kết ngân hàng, bạn nên đăng ký các sự kiện callback lắng nghe kết quả bằng hàm TingeeBankLink.Setup(config).

TingeeBankLink.Setup({
  // Kích thước mặc định của cửa sổ Popup
  size: 'desktop', 

  // Tùy chỉnh màu sắc chủ đạo
  theme: {
    primaryColor: '#1E88E5'
  },
  
  // Sự kiện: Liên kết tài khoản ngân hàng thành công
  onSuccess: function(data) {
    console.log("Liên kết thành công!", data);
    // Ví dụ: làm mới danh sách tài khoản hoặc thông báo thành công
  },
  
  // Sự kiện: Liên kết thất bại (ví dụ: lỗi nghiệp vụ từ ngân hàng)
  onFailed: function(data) {
    console.error("Liên kết thất bại:", data.errorMessage);
  },
  
  // Sự kiện: Người dùng chủ động hủy liên kết (ví dụ: nhấn nút X đóng popup)
  onCancelled: function(data) {
    console.log("Người dùng hủy liên kết:", data);
  },
  
  // Sự kiện: Có lỗi hệ thống phát sinh trong SDK
  onError: function(data) {
    console.error("Lỗi hệ thống SDK:", data);
  },
  
  // Sự kiện: Popup đóng lại (chạy sau các callback thành công/thất bại/hủy)
  onClose: function() {
    console.log("Cửa sổ SDK đã đóng.");
  }
});

---

3. Hiển thị Giao diện Liên kết

Sau khi gọi Backend của bạn và nhận được url (SDK URL từ OpenAPI), bạn gọi hàm TingeeBankLink.Url.Open(url, options) để kích hoạt giao diện SDK.

// url nhận được từ backend của bạn thông qua OpenAPI v1/create-bank-link-session
const bankLinkUrl = "https://uat-bank-link.tingee.vn?token=...";

// Mở SDK
TingeeBankLink.Url.Open(bankLinkUrl);

[!TIP] Bạn có thể truyền các sự kiện callback và các cấu hình kích thước đè lên cấu hình toàn cục (Global Setup) ngay trong tham số thứ 2 của hàm Open nếu cần tùy chỉnh riêng cho từng phiên.

---

4. Tùy chỉnh Kích thước & Chế độ Hiển thị

4.1. Kích thước (Size Presets)

SDK hỗ trợ các thiết lập kích thước cửa sổ Popup có sẵn:

Giá trị	Mô tả
small	Modal kích thước nhỏ.
medium	Modal kích thước vừa (mặc định).
large	Modal kích thước lớn.

Bạn cũng có thể cấu hình kích thước tùy chỉnh chi tiết:

TingeeBankLink.Url.Open(url, {
  size: {
    width: 960,
    height: '92%',
    maxWidth: 'calc(100vw - 32px)',
    maxHeight: 820,
    borderRadius: 24
  }
});

4.2. Chế độ hiển thị Inline (Inline Container)

Nếu bạn không muốn hiển thị dưới dạng Popup mà muốn nhúng trực tiếp giao diện vào một phân vùng (Container) có sẵn trên trang web:

<!-- Khai báo vùng chứa (container) -->
<div id="bank-link-container" style="width: 100%; height: 760px;"></div>

<script>
  // Gọi SDK render trực tiếp vào container chỉ định bằng ID
  TingeeBankLink.Url.Open(url, {
    containerId: 'bank-link-container'
  });
</script>

---

5. Ví dụ Tích hợp Framework

React

BankLinkButton.tsx

import React, { useEffect } from 'react';

// Khai báo kiểu TypeScript toàn cục tránh báo lỗi compiler
declare global {
  interface Window {
    TingeeBankLink: any;
  }
}

export default function BankLinkButton() {
  useEffect(() => {
    if (window.TingeeBankLink) {
      window.TingeeBankLink.Setup({
        size: 'desktop',
        onSuccess: (data: any) => {
          console.log("Liên kết thành công", data);
          // Thực hiện cập nhật UI hoặc gọi API tải lại dữ liệu tài khoản
        },
        onCancelled: () => console.log("Khách hàng đóng SDK"),
      });
    }
  }, []);

  const handleOpenSDK = async () => {
    try {
      // Gọi API nội bộ của bạn để sinh link liên kết ngân hàng
      const response = await fetch('/api/bank-link/session', { method: 'POST' });
      const { url } = await response.json();
      
      if (window.TingeeBankLink) {
        window.TingeeBankLink.Url.Open(url);
      } else {
        alert("SDK chưa được tải thành công!");
      }
    } catch (error) {
      console.error("Lỗi khởi tạo liên kết ngân hàng", error);
    }
  };

  return (
    <button onClick={handleOpenSDK} className="btn-link">
      Liên kết tài khoản ngân hàng ngay
    </button>
  );
}

Angular

bank-link.component.ts

import { Component, OnInit } from '@angular/core';

declare var TingeeBankLink: any; // Khai báo biến toàn cục

@Component({
  selector: 'app-bank-link',
  template: `
    <button (click)="startLinking()">Liên kết tài khoản ngân hàng</button>
  `
})
export class BankLinkComponent implements OnInit {

  ngOnInit() {
    if (typeof TingeeBankLink !== 'undefined') {
      TingeeBankLink.Setup({
        size: 'desktop',
        onSuccess: (data: any) => {
          console.log("Liên kết thành công", data);
        },
        onCancelled: () => console.log("Khách hàng đã hủy")
      });
    }
  }

  async startLinking() {
    try {
      // Gọi service backend của bạn lấy URL liên kết ngân hàng
      const url = await this.bankLinkService.createSession();
      TingeeBankLink.Url.Open(url);
    } catch (error) {
      console.error("Lỗi liên kết ngân hàng", error);
    }
  }
}

Vue 3

BankLink.vue

<script setup>
import { onMounted } from 'vue';

onMounted(() => {
  if (window.TingeeBankLink) {
    window.TingeeBankLink.Setup({
      size: 'desktop',
      onSuccess: (data) => {
        console.log("Liên kết thành công", data);
      },
      onCancelled: () => console.log("Khách hàng hủy"),
    });
  }
});

const startLinking = async () => {
  try {
    const response = await fetch('/api/bank-link/session', { method: 'POST' });
    const { url } = await response.json();
    
    if (window.TingeeBankLink) {
      window.TingeeBankLink.Url.Open(url);
    }
  } catch (error) {
    console.error("Lỗi tạo session liên kết ngân hàng", error);
  }
};
</script>

<template>
  <button @click="startLinking">Liên kết tài khoản ngân hàng</button>
</template>

---

6. Định dạng Dữ liệu trả về (Callback Payloads)

6.1. Khi thành công (onSuccess)

Trả về một JSON Object chứa thông tin tài khoản ngân hàng liên kết thành công:

{
  "status": "success",
  "bankName": "BIDV",
  "merchantAccountNumberId": 456,
  "vaAccountNumber": "1234567890",
  "shopId": 123
}

6.2. Khi thất bại (onFailed)

Trả về thông tin mã lỗi nghiệp vụ chi tiết:

{
  "status": "failed",
  "errorCode": "BANK_CONFIG_NOT_EXIST",
  "errorMessage": "Cấu hình ngân hàng không tồn tại"
}

6.3. Khi người dùng chủ động đóng (onCancelled)

{
  "status": "cancelled",
  "errorCode": "USER_CLOSED"
}

---

7. Xử lý qua Redirect URL

Nếu bạn đã cung cấp tham số redirectUrl khi tạo session ở Backend, SDK sẽ tự động điều hướng toàn bộ trình duyệt web của khách hàng về địa chỉ đó kèm các thông số kết quả dưới dạng query parameters:

https://merchant.example.vn/bank-link/callback?status=success&bankName=BIDV&merchantAccountNumberId=456&shopId=123

Đối tác có thể đọc thông tin trên URL callback này để hiển thị thông báo kết quả tương ứng.

---

8. Đồng bộ kết quả qua Webhook (Khuyến nghị)

Mặc dù SDK và Redirect URL cung cấp phản hồi lập tức trên giao diện người dùng (Client-side), việc sử dụng Webhook (Server-side) là giải pháp an toàn và tin cậy nhất để đồng bộ trạng thái liên kết tài khoản ngân hàng về hệ thống của bạn.

Hệ thống Tingee sẽ tự động gửi một POST request chứa thông tin tài khoản ngân hàng liên kết thành công ngay sau khi sự kiện diễn ra.

Chi tiết về cấu hình, định dạng dữ liệu (payload) và cách xác thực chữ ký bảo mật vui lòng xem tại tài liệu Webhook liên kết ngân hàng.