@tingee/sdk-node

SDK chính thức tích hợp Tingee Open API cho Node.js / TypeScript

Cài đặt

npm install @tingee/sdk-node
# hoặc
yarn add @tingee/sdk-node
# hoặc
pnpm add @tingee/sdk-node

Bắt đầu nhanh

import { TingeeClient, isSuccessResponse } from '@tingee/sdk-node'

const client = new TingeeClient({
  secretKey:   process.env.TINGEE_SECRET_KEY!,
  clientId:    process.env.TINGEE_CLIENT_ID!,
  environment: 'production', // 'uat' | 'production', mặc định 'production'
  timeout: 90000,            // mặc định 90s
  baseUrl: 'https://uat-open-api.tingee.vn', // tùy chọn, ghi đè environment
})

const result = await client.merchant.getPaging({ maxResultCount: 10, skipCount: 0 })
if (isSuccessResponse(result)) {
  console.log(result.data)
} else {
  console.error(`Lỗi ${result.code}: ${result.message}`)
}

Cấu hình

| Tùy chọn | Kiểu | Mặc định | Mô tả | |---|---|---|---| | secretKey | string | — | Bắt buộc. Secret key từ Tingee Dashboard | | clientId | string | — | Bắt buộc. Client ID từ Tingee Dashboard | | environment | 'uat' \| 'production' | 'production' | Môi trường API | | baseUrl | string | — | Ghi đè URL (bỏ qua environment) | | timeout | number | 90000 | Timeout (ms) |

Gọi API

Tất cả phương thức nằm trong client.*:

// Merchant — lấy danh sách
const result = await client.merchant.getPaging({ maxResultCount: 10, skipCount: 0 })
if (isSuccessResponse(result)) {
  result.data.items.forEach(m => console.log(m.name))
}

// Shop — lấy danh sách
const shops = await client.shop.getPaging({ maxResultCount: 10, skipCount: 0 })

// Direct Debit
const sub = await client.directDebit.getSubscriptionStatus({
  requestId:      'uuid-here',
  subscriptionId: 'uuid-here',
  tokenRef:       'token-ref',
})

Lưu ý: SDK trả về TingeeApiResponse với code và message. Kiểm tra code === '00' hoặc isSuccessResponse(result) để xác định thành công — SDK không tự throw khi code !== '00'.

Xác thực Webhook

Khi Tingee gọi vào endpoint webhook của bạn, dùng client.verifyWebhookSignature():

// Express.js
app.post('/webhook/tingee', express.json(), (req, res) => {
  const result = client.verifyWebhookSignature({
    signature: req.headers['x-signature']         as string,
    timestamp: req.headers['x-request-timestamp'] as string,
    body:      req.body,
  })

  if (isErrorResponse(result)) {
    return res.status(401).json({ error: result.message })
  }

  const { transactionCode, amount, bank } = req.body
  // Xử lý giao dịch...
  res.json({ received: true })
})

// NestJS
@Post('webhook/tingee')
handleWebhook(@Req() req: Request, @Body() body: Record<string, any>) {
  const result = this.tingeeClient.verifyWebhookSignature({
    signature: req.headers['x-signature'] as string,
    timestamp: req.headers['x-request-timestamp'] as string,
    body,
  })
  if (isErrorResponse(result)) throw new UnauthorizedException(result.message)
  // ...
}

Bank Constants

import { BankNameEnum, getBankCode, getBankShortName, getBankBin } from '@tingee/sdk-node'

getBankCode(BankNameEnum.VIETCOMBANK)       // 'VCB'
getBankShortName(BankNameEnum.VIETCOMBANK)  // 'Vietcombank'
getBankBin(BankNameEnum.VIETCOMBANK)        // '970410'

Liên hệ & Hỗ trợ

📧 Email: [email protected] 💬 Telegram: @tingeesupport 🌐 Website: tingee.vn

Xem thêm

• CHANGELOG
• Tài liệu Tingee Open API
• Tài liệu Tingee Developer
• Trang chủ Tingee