Thư viện SDK
Tingee SDK là bộ thư viện chính thức giúp lập trình viên tích hợp Tingee Open API vào ứng dụng nhanh chóng, an toàn và không cần xử lý thủ công các chi tiết kỹ thuật như tạo chữ ký HMAC-SHA512, quản lý timestamp hay xử lý HTTP headers.
Tích hợp nhanh
Cài đặt SDK chỉ bằng một lệnh. Gọi API bằng một dòng code thay vì hàng chục dòng xử lý HTTP + signature.
Tự động xác thực
SDK tự động tạo chữ ký HMAC-SHA512 và gắn headers x-signature, x-request-timestamp cho mọi request.
Type-safe
Hỗ trợ đầy đủ TypeScript types, Java DTO, C# models và PHP typed classes — giảm thiểu lỗi runtime.
Ngôn ngữ hỗ trợ
| Ngôn ngữ | Package | Yêu cầu |
|---|---|---|
| Node.js / TypeScript | @tingee/sdk-node | Node.js ≥ 18 |
| Java | vn.tingee:sdk-java | Java ≥ 17 |
| C# / .NET | Tingee.Sdk | .NET 8+ |
| PHP | tingee/sdk-php | PHP ≥ 8.0 |
SDK vs. Gọi API thủ công
| Gọi API thủ công | Dùng SDK | |
|---|---|---|
| Xác thực | Tự viết HMAC-SHA512, format timestamp, gắn headers | ✓ Tự động |
| Serialization | Tự serialize/deserialize JSON | ✓ Tự động, có typed response |
| Bảo trì | Phải cập nhật khi API thay đổi | ✓ Cập nhật SDK version |
| Code lượng | ~30 dòng mỗi API call | ✓ 1–3 dòng |
| Type safety | Không có | ✓ Full type support |
Ví dụ: Tạo Virtual Account
✕ Gọi API thủ công (Node.js)
import axios from 'axios';
import { createHmac } from 'crypto';
import { format } from 'date-fns';
const body = {
accountType: 'personal-account',
bankBin: '970418',
accountNumber: '0935926988',
accountName: 'NGUYEN THI HUYEN',
identity: '040191014068',
mobile: '0123456789',
};
const timestamp = format(new Date(), 'yyyyMMddHHmmssSSS');
const message = `${timestamp}:${JSON.stringify(body)}`;
const signature = createHmac('sha512', 'YOUR_SECRET_KEY').update(message).digest('hex');
const res = await axios.post('https://open-api.tingee.vn/v1/create-va', body, {
headers: {
'x-signature': signature,
'x-request-timestamp': timestamp,
'x-client-id': 'YOUR_CLIENT_ID',
'Content-Type': 'application/json',
},
});
✓ Dùng SDK
import { TingeeClient, isSuccessResponse } from '@tingee/sdk-node';
const client = new TingeeClient({
secretKey: process.env.TINGEE_SECRET_KEY!,
clientId: process.env.TINGEE_CLIENT_ID!,
});
const result = await client.bank.createVa({
accountType: 'personal-account',
bankBin: '970418',
accountNumber: '0935926988',
accountName: 'NGUYEN THI HUYEN',
identity: '040191014068',
mobile: '0123456789',
});
if (isSuccessResponse(result)) {
console.log('confirmId:', result.data.confirmId);
}
Nhóm API
SDK tổ chức methods theo nhóm tính năng, giúp dễ khám phá và sử dụng:
| Nhóm | Mô tả | Docs tham khảo |
|---|---|---|
bank | Tài khoản ảo (VA), QR Code, biến động số dư | Banking · QR Code |
merchant | Quản lý Merchant, cấu hình | Master Merchant |
shop | Quản lý cửa hàng | Master Merchant |
device | Thiết bị TingeeBox, đọc mã bảo mật, hiển thị QR | TingeeBox |
deepLink | Tạo Deep Link thanh toán | Deep Link |
directDebit | Đăng ký, trích nợ, hoàn tiền | Direct Debit |
transaction | Tra cứu lịch sử giao dịch | Banking |
accountNumber | Danh sách số tài khoản | Banking |
user | Xác thực mã giới thiệu | — |
Tham khảo
Đối tác vui lòng tham khảo mã nguồn SDK tại đây: github.com/tingeehub