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

Bên cạnh việc chuyển hướng (redirect) người dùng trực tiếp đến Checkout URL, Tingee cung cấp Frontend SDK giúp bạn nhúng trải nghiệm thanh toán vào thẳng website của mình dưới dạng Popup (Modal). Điều này giúp giữ chân khách hàng ở lại trang web của bạn và tối ưu hóa tỷ lệ chuyển đổi.

1. Cài đặt SDK

Tích hợp SDK thông qua thẻ <script> nhúng vào HTML (ví dụ: index.html của React/Vue/Angular). Tùy thuộc vào môi trường bạn đang phát triển (UAT hay PROD), hãy sử dụng đường dẫn tương ứng:

Môi trường UAT:

<script src="https://uat-payment-gateway.tingee.vn/js/tingee.js"></script>

Môi trường PROD:

<script src="https://payment-gateway.tingee.vn/js/tingee.js"></script>

---

2. Cấu hình Toàn cục (Global Setup)

Để ứng dụng của bạn hoạt động mượt mà, bạn nên cấu hình SDK một lần duy nhất ngay khi ứng dụng vừa khởi động.

Sử dụng hàm Tingee.Setup(config) để định nghĩa các sự kiện lắng nghe (callbacks) dùng chung cho toàn bộ website.

// Khởi tạo ngay từ đầu (ví dụ: trong file index.js, main.ts, hoặc App.tsx)
window.Tingee.Setup({
  // Cấu hình hiển thị (tùy chọn)
  size: 'medium', // 'small' | 'medium' | 'large' (mặc định 'medium')
  
  // Giao dịch thành công
  onSuccess: function(data) {
    console.log("Thanh toán thành công!", data);
    window.location.href = "/checkout/success";
  },
  
  // Giao dịch thất bại / hết hạn
  onFailed: function(error) {
    console.error("Giao dịch thất bại hoặc hết hạn", error);
  },
  
  // Người dùng chủ động hủy (nhấn nút X)
  onCancelled: function() {
    console.log("Người dùng đã hủy thanh toán.");
  },
  
  // Cửa sổ thanh toán đóng lại (dù thành công hay thất bại)
  onClose: function() {
    console.log("Popup thanh toán đã được đóng.");
  }
});

---

3. Mở Cửa sổ Thanh toán

Sau khi hệ thống Backend của bạn gọi API Tạo link thanh toán và trả về Checkout URL, bạn chỉ cần gọi hàm Tingee.Url.Open() để hiển thị popup.

// checkoutUrl lấy từ API backend (ví dụ: https://pay.tingee.vn/checkout?token=xxx&s=yyy)
const checkoutUrl = "https://pay.tingee.vn/checkout?...";

// Hiển thị Popup
window.Tingee.Url.Open(checkoutUrl);

(Bạn cũng có thể truyền thêm object cấu hình vào tham số thứ 2 của hàm Open nếu muốn ghi đè cấu hình global cho riêng giao dịch này).

---

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

Dưới đây là ví dụ cách khởi tạo (Global Setup) và gọi hàm hiển thị (Open) đối với các Frontend Framework phổ biến:

React

App.tsx

import React, { useEffect } from 'react';

// Nếu dùng TypeScript, có thể cần khai báo global để tránh báo lỗi
// declare global { interface Window { Tingee: any; } }

export default function App() {
  // 1. Cấu hình Global khi ứng dụng khởi chạy
  useEffect(() => {
    // Đảm bảo script ở index.html đã load xong
    if (window.Tingee) {
      window.Tingee.Setup({
        size: 'medium',
        onSuccess: (data: any) => {
          console.log("Thanh toán thành công", data);
          // Điều hướng React Router
          // navigate('/success');
        },
        onCancelled: () => console.log("Khách hàng hủy"),
      });
    }
  }, []);

  // 2. Hàm xử lý nút thanh toán
  const handlePayment = async () => {
    try {
      // Giả lập gọi API nội bộ lấy Checkout URL
      const response = await fetch('/api/create-payment');
      const { checkoutUrl } = await response.json();
      
      // Mở Popup
      if (window.Tingee) {
        window.Tingee.Url.Open(checkoutUrl);
      } else {
        alert("Không tìm thấy SDK Tingee!");
      }
    } catch (error) {
      console.error("Lỗi tạo thanh toán", error);
    }
  };

  return (
    <div>
      <h1>Giỏ hàng</h1>
      <button onClick={handlePayment}>Thanh toán ngay</button>
    </div>
  );
}

Angular

app.component.ts

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

declare var Tingee: any; // Khai báo tránh lỗi TypeScript

@Component({
  selector: 'app-root',
  template: `
    <h1>Giỏ hàng</h1>
    <button (click)="handlePayment()">Thanh toán ngay</button>
  `
})
export class AppComponent implements OnInit {

  // 1. Cấu hình Global khi ứng dụng khởi chạy
  ngOnInit() {
    if (typeof Tingee !== 'undefined') {
      Tingee.Setup({
        size: 'medium',
        onSuccess: (data: any) => {
          console.log("Thanh toán thành công", data);
          // this.router.navigate(['/success']);
        },
        onCancelled: () => console.log("Khách hàng hủy")
      });
    }
  }

  // 2. Hàm xử lý nút thanh toán
  async handlePayment() {
    try {
      // Giả lập gọi API nội bộ lấy Checkout URL
      const checkoutUrl = await this.paymentService.createLink();
      
      // Mở Popup
      Tingee.Url.Open(checkoutUrl);
    } catch (error) {
      console.error("Lỗi tạo thanh toán", error);
    }
  }
}

Vue 3

App.vue

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

// 1. Cấu hình Global khi ứng dụng khởi chạy
onMounted(() => {
  if (window.Tingee) {
    window.Tingee.Setup({
      size: 'medium',
      onSuccess: (data) => {
        console.log("Thanh toán thành công", data);
        // router.push('/success');
      },
      onCancelled: () => console.log("Khách hàng hủy"),
    });
  }
});

// 2. Hàm xử lý nút thanh toán
const handlePayment = async () => {
  try {
    // Giả lập gọi API nội bộ lấy Checkout URL
    const response = await fetch('/api/create-payment');
    const { checkoutUrl } = await response.json();
    
    // Mở Popup
    window.Tingee.Url.Open(checkoutUrl);
  } catch (error) {
    console.error("Lỗi tạo thanh toán", error);
  }
};
</script>

<template>
  <div>
    <h1>Giỏ hàng</h1>
    <button @click="handlePayment">Thanh toán ngay</button>
  </div>
</template>

---

5. Lợi ích khi dùng SDK

• Không rời bỏ trang: Toàn bộ quá trình quét QR hoặc nhập thẻ diễn ra trên Popup, người dùng luôn nhìn thấy bối cảnh website của bạn ở phía sau.
• Bắt sự kiện (Event-driven): Website của bạn biết được chính xác khi nào người dùng tắt Popup hoặc khi thanh toán vừa thành công để lập tức cập nhật lại giao diện (như giỏ hàng, thông báo) mà không phải reload lại trang.