Bắt đầu ngay

Giới thiệu

Để triển khai tích hợp với hệ thống Tingee, đối tác bắt buộc phải sử dụng Client ID và Secret Token và Sinh chữ ký nhằm xác thực và đảm bảo tính hợp lệ cho mỗi yêu cầu API.
Tài liệu này hướng dẫn chi tiết cách truy xuất các thông tin trên cho từng tài khoản đối tác.

---

Hướng dẫn lấy Client ID & Secret Token

• Bước 1. Truy cập vào hệ thống Tingee BaaS Portal (hoặc trang thử nghiệm uat-baas-portal.tingee.vn) và đăng ký/đăng nhập tài khoản của Đối tác.

• Bước 2. Tại menu Sidebar bên trái, click chọn mục API Credentials (hoặc truy cập trực tiếp tại baas.tingee.vn/api-credentials).

• Bước 3. Nhấp vào nút Tạo mới (hoặc Tạo mới API Credentials) để mở modal tạo bộ xác thực:

  • Thông tin cơ bản: Điền Tên gợi nhớ (để phân biệt mục đích sử dụng, ví dụ: Live Credentials, POS Test, Mobile App...) và Mô tả.
  • Quyền truy cập: Chọn nhóm sản phẩm/dịch vụ mà Credentials này được phép gọi API (Cổng thanh toán, QR, Bank Link, Direct Debit, v.v., hoặc click chọn Chọn tất cả).

• Bước 4. Bấm nút Tạo API Credentials để lưu cấu hình. Hệ thống sẽ tạo bộ thông tin định danh và hiển thị tại danh sách gồm Client ID và Secret Token. Đối tác dùng nút Sao chép (copy) để lấy các thông tin này đưa vào cấu hình tích hợp.

---

Sinh chữ ký Signature

Mỗi API request gửi đến Tingee cần kèm theo chữ ký số (signature) để đảm bảo tính toàn vẹn và xác thực danh tính đối tác.

Công thức sinh chữ ký

x-signature = HMAC_SHA512( x-request-timestamp + ":" + requestBody, secretToken )

Trong đó:

• x-request-timestamp — Thời điểm gửi request, format yyyyMMddHHmmssSSS (múi giờ UTC+7)
• requestBody — Chuỗi JSON của request body, đã qua JSON.stringify() (minified, không có khoảng trắng thừa)
• secretToken — Secret Token lấy từ trang Developers của tài khoản đối tác

Headers bắt buộc

Header	Bắt buộc	Ví dụ
x-client-id	✅	Mã định danh của đối tác do TINGEE cung cấp Xem cách lấy tại đây
x-request-timestamp	✅	20260101101122333
x-signature	✅	Chữ ký SHA-512
Content-Type	✅	application/json

Code mẫu

Node.js

const crypto = require('crypto');

function generateSignature(timestamp, requestBody, secretToken) {
  const message = `${timestamp}:${requestBody}`;
  return crypto
    .createHmac('sha512', secretToken)
    .update(message, 'utf8')
    .digest('hex');
}

// Ví dụ sử dụng
const timestamp = new Date()
  .toISOString()
  .replace(/[-:T.Z]/g, '')
  .slice(0, 17); // "yyyyMMddHHmmssSSS"

const body = JSON.stringify({ clientId: 'abc123', amount: 50000 });
const signature = generateSignature(timestamp, body, 'YOUR_SECRET_TOKEN');

// Gắn vào headers khi gọi API
const headers = {
  'Content-Type': 'application/json',
  'x-client-id': 'YOUR_CLIENT_ID',
  'x-request-timestamp': timestamp,
  'x-signature': signature,
};

C#

using System;
using System.Security.Cryptography;
using System.Text;

public class TingeeSignature
{
    public static string Generate(string timestamp, string requestBody, string secretToken)
    {
        var message = $"{timestamp}:{requestBody}";
        var keyBytes = Encoding.UTF8.GetBytes(secretToken);
        var messageBytes = Encoding.UTF8.GetBytes(message);

        using (var hmac = new HMACSHA512(keyBytes))
        {
            var hash = hmac.ComputeHash(messageBytes);
            return BitConverter.ToString(hash).Replace("-", "").ToLower();
        }
    }

    // Ví dụ sử dụng
    public static void Example()
    {
        var timestamp = DateTime.Now.ToString("yyyyMMddHHmmssfff");
        var body = "{\"clientId\":\"abc123\",\"amount\":50000}";
        var signature = Generate(timestamp, body, "YOUR_SECRET_TOKEN");

        // Gắn vào headers khi gọi API
        // request.Headers["x-client-id"] = "YOUR_CLIENT_ID";
        // request.Headers["x-request-timestamp"] = timestamp;
        // request.Headers["x-signature"] = signature;
    }
}

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

public class TingeeSignature {
    public static String generate(String timestamp, String requestBody, String secretToken)
            throws Exception {
        String message = timestamp + ":" + requestBody;

        Mac hmac = Mac.getInstance("HmacSHA512");
        SecretKeySpec keySpec = new SecretKeySpec(
            secretToken.getBytes(StandardCharsets.UTF_8), "HmacSHA512");
        hmac.init(keySpec);

        byte[] hash = hmac.doFinal(message.getBytes(StandardCharsets.UTF_8));
        StringBuilder sb = new StringBuilder();
        for (byte b : hash) sb.append(String.format("%02x", b));
        return sb.toString();
    }

    public static void main(String[] args) throws Exception {
        String timestamp = LocalDateTime.now()
            .format(DateTimeFormatter.ofPattern("yyyyMMddHHmmssSSS"));
        String body = "{\"clientId\":\"abc123\",\"amount\":50000}";
        String signature = generate(timestamp, body, "YOUR_SECRET_TOKEN");

        System.out.println("x-signature: " + signature);
    }
}

PHP

function generateSignature(string $timestamp, string $requestBody, string $secretToken): string {
    $message = $timestamp . ':' . $requestBody;
    return hash_hmac('sha512', $message, $secretToken);
}

// Ví dụ sử dụng
$timestamp = date('YmdHisu'); // "yyyyMMddHHmmssSSS" — chú ý milliseconds
$body = json_encode(['clientId' => 'abc123', 'amount' => 50000]);
$signature = generateSignature($timestamp, $body, 'YOUR_SECRET_TOKEN');

$headers = [
    'Content-Type: application/json',
    'x-client-id: YOUR_CLIENT_ID',
    'x-request-timestamp: ' . $timestamp,
    'x-signature: ' . $signature,
];

Lưu ý quan trọng

• Không chia sẻ secretToken trong mã nguồn hoặc repository công khai.
• Timestamp không được vượt quá thời điểm hiện tại và không được cũ hơn 10 phút so với thời gian máy chủ Tingee (UTC+7).
• requestBody phải là kết quả của JSON.stringify(body) — chuỗi JSON minified, không thêm khoảng trắng hay format lại, để đảm bảo chữ ký khớp chính xác.

---

Cấu hình Webhook

• Tingee sẽ gửi các Requests HTTP (method POST) đến Webhook url của Đối tác khi phát sinh giao dịch với các tài khoản liên kết trên Tingee.
  

• Đối tác cấu hình và quản lý tại mục Webhook trên menu Sidebar của Portal:

• Nhấn nút Tạo mới để mở modal cấu hình endpoint nhận sự kiện:

  • Thông tin cơ bản:
    • Tên endpoint: Nhập tên gợi nhớ.
    • URL webhook endpoint: Nhập địa chỉ HTTP/HTTPS nhận dữ liệu. Đối tác có thể bấm Kiểm tra kết nối (Connection Test) để kiểm tra tính khả dụng của URL.
  • Phạm vi sự kiện: Chọn nhóm sự kiện muốn nhận thông báo (ví dụ: QR Code).
    • Nếu chọn QR Code, chọn Loại áp dụng:
      • Tất cả: Nhận sự kiện với mọi tài khoản.
      • Số tài khoản ảo: Chọn các tài khoản cụ thể muốn nhận sự kiện.
      • Cửa hàng: Chọn các cửa hàng cụ thể muốn nhận sự kiện.
    • Đồng thời có thể thiết lập Danh sách đen (Blacklist) để loại trừ các số tài khoản không muốn gửi webhook.
  • Cấu hình gọi lại webhook (Retry): Bật/tắt retry, thiết lập điều kiện gửi lại (timeout, lỗi http status) và các thông số tùy chỉnh như timeout (5-10 giây), số lần gửi lại (1-5 lần), khoảng chờ (2-3600 giây).
  • Kiểu chứng thực Webhooks: Chọn phương thức bảo mật đính kèm vào header khi Tingee gửi webhook (None, API Key, hoặc API Credentials).

• Đối tác có thể kích hoạt/vô hiệu hóa (bật/tắt) hoặc chỉnh sửa cấu hình Webhook trực tiếp từ màn hình quản lý.

---

Nhật ký Webhook

• Đối tác có thể xem lịch sử gửi Webhook (Trạng thái webhook, số lần gửi lại, HTTP status code...) của từng endpoint trực tiếp tại trang Sử dụng (Usage), tab Lịch sử webhook của Portal.
• Tại đây, Đối tác có thể theo dõi chi tiết trạng thái delivery, số lần retry, HTTP response status code, thời gian phản hồi, hoặc bấm Xem chi tiết để xem payload Request/Response cụ thể của từng sự kiện webhook.