TheSieuToc SDK 🚀

A high-performance, type-safe TypeScript SDK for integrating with the TheSieuToc API (Vietnamese Card Payment Gateway).

✨ Features

• 🚀 Type-Safe: Fully typed with TypeScript for a better developer experience.
• 🛠 Easy Integration: Clean and intuitive API for card submission and status checking.
• 💎 Premium Design: Built with modern software patterns.
• 📦 Lightweight: Minimal dependencies.

📦 Installation

npm install thesieutoc-sdk

or

yarn add thesieutoc-sdk

🚀 Quick Start

1. Initialize the Client

import { TheSieuTocClient } from 'thesieutoc-sdk';

const client = new TheSieuTocClient('YOUR_API_KEY');

2. Submit a Card

const result = await client.submitCard({
  type: 'Viettel',
  mathe: '1234567890123',
  seri: '10001234567',
  menhgia: 50000,
  content: 'unique_order_id_123'
});

console.log(result.msg); // Thẻ đã gửi lên hệ thống chờ xử lý!

3. Check Card Status

const status = await client.checkCardStatus('unique_order_id_123');
console.log(status.msg); // Thẻ thành công

4. Fetch Discounts

const discounts = await client.getDiscounts();
const viettel = discounts.find(d => d.card_type === 'Viettel');
console.log(viettel?.discount['50000']);

5. Handle Callback (Webhook)

When TheSieuToc sends a callback to your server, you can use the SDK to validate the data structure:

import { TheSieuTocClient, CardCallbackData } from 'thesieutoc-sdk';

// In your Express route
app.post('/callback', (req, res) => {
  const data = req.body as CardCallbackData;

  if (TheSieuTocClient.isValidCallback(data)) {
    if (data.status === 'thanhcong') {
      console.log(`Card success: ${data.real_amount} VND`);
    } else {
      console.log(`Card failed: ${data.noidung}`);
    }
    res.send('OK');
  } else {
    res.status(400).send('Invalid data');
  }
});

📖 API Reference

TheSieuTocClient

constructor(apiKey: string)

Initializes the client with your secret API key.

submitCard(data: CardSubmissionRequest): Promise<CardSubmissionResponse>

Sends card information to the system for processing.

checkCardStatus(requestId: string): Promise<CheckStatusResponse>

Queries the current status of a card submission using the requestId.

getDiscounts(username?: string): Promise<DiscountInfo>

Fetches the latest card discount rates. Optional username for account-specific rates.

🎨 Constants & Types

The SDK exports all necessary types and constants to handle responses effectively.

import { ERROR_CODES, CHECK_STATUS_CODES } from 'thesieutoc-sdk';

console.log(ERROR_CODES['54']); // Chưa Nhập API key

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Built with ❤️ by WangYi