Bắt đầu nhanh

Hướng dẫn này giúp bạn thực hiện API call đầu tiên với Tingee SDK chỉ trong vài phút.

Yêu cầu trước khi bắt đầu

• Đã cài đặt SDK cho ngôn ngữ của bạn
• Có clientId và secretKey từ Tingee Dashboard

---

1. Khởi tạo Client

Node.js

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

const client = new TingeeClient({
  secretKey:   process.env.TINGEE_SECRET_KEY!,
  clientId:    process.env.TINGEE_CLIENT_ID!,
  environment: 'uat', // dùng 'uat' khi test, 'production' khi go-live
});

Java

import vn.tingee.sdk.TingeeClient;
import vn.tingee.sdk.client.TingeeEnvironment;

TingeeClient client = TingeeClient.builder(
        System.getenv("TINGEE_SECRET_KEY"),
        System.getenv("TINGEE_CLIENT_ID"))
    .environment(TingeeEnvironment.UAT)
    .build();

C#

using Tingee.Sdk.Client;

var client = new TingeeClient(new TingeeClientOptions
{
    SecretKey   = Environment.GetEnvironmentVariable("TINGEE_SECRET_KEY")!,
    ClientId    = Environment.GetEnvironmentVariable("TINGEE_CLIENT_ID")!,
    Environment = TingeeEnvironment.Uat,
});

PHP

<?php
require_once 'vendor/autoload.php';

use Tingee\Sdk\TingeeClient;

$client = new TingeeClient(
    secretKey:   $_ENV['TINGEE_SECRET_KEY'],
    clientId:    $_ENV['TINGEE_CLIENT_ID'],
    environment: 'uat',
);

---

2. Gọi API đầu tiên

Ví dụ: Lấy danh sách Merchant.

Node.js

const result = await client.merchant.getPaging({
  maxResultCount: 10,
  skipCount: 0,
});

if (isSuccessResponse(result)) {
  console.log('Danh sách merchants:');
  result.data.items.forEach(m => console.log(` - ${m.name}`));
} else {
  console.error(`Lỗi ${result.code}: ${result.message}`);
}

Java

var req = new OpenApiGetPagingMerchantsDto(0, 10);
var result = client.merchant.getPaging(req);

if (result.isSuccess()) {
    System.out.println("Danh sách merchants:");
    result.getData().getItems().forEach(m -> System.out.println(" - " + m));
} else {
    System.err.println("Lỗi " + result.getCode() + ": " + result.getMessage());
}

C#

var result = await client.Merchant.GetPagingAsync(new OpenApiGetPagingMerchantsDto
{
    SkipCount      = 0,
    MaxResultCount = 10,
});

if (result.IsSuccess)
{
    Console.WriteLine("Danh sách merchants:");
    foreach (var m in result.Data!.Items!)
        Console.WriteLine($" - {m.Name}");
}
else
{
    Console.Error.WriteLine($"Lỗi {result.Code}: {result.Message}");
}

PHP

$result = $client->merchant->getPaging(
    filter: null, sorting: null, skipCount: 0, maxResultCount: 10
);

if ($result->isSuccess()) {
    echo "Danh sách merchants:\n";
    foreach ($result->getData()->items as $m) {
        echo " - {$m->name}\n";
    }
} else {
    echo "Lỗi {$result->getCode()}: {$result->getMessage()}\n";
}

---

3. Xử lý Response

SDK trả về TingeeApiResponse cho mọi API call:

{
  "code": "00",
  "message": "Success",
  "data": { ... }
}

SDK không tự throw exception

Khi code !== '00', SDK không throw exception. Bạn cần kiểm tra code hoặc dùng helper:

Node.js

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

if (isSuccessResponse(result)) {
  // code === '00' → xử lý result.data
} else if (isErrorResponse(result)) {
  // code !== '00' → xử lý lỗi
  console.error(`${result.code}: ${result.message}`);
}

Java

if (result.isSuccess()) {
    // code == "00" → xử lý result.getData()
} else {
    // code != "00" → xử lý lỗi
    System.err.println(result.getCode() + ": " + result.getMessage());
}

C#

if (result.IsSuccess)
{
    // Code == "00" → xử lý result.Data
}
else
{
    // Code != "00" → xử lý lỗi
    Console.Error.WriteLine($"{result.Code}: {result.Message}");
}

PHP

if ($result->isSuccess()) {
    // code === '00' → xử lý $result->getData()
} else {
    // code !== '00' → xử lý lỗi
    echo $result->getCode() . ': ' . $result->getMessage();
}

---

4. Thêm ví dụ

Danh sách ngân hàng hỗ trợ

Node.js

const banks = await client.bank.getBanks();
if (isSuccessResponse(banks)) {
  banks.data.forEach(b => console.log(`${b.shortName} (BIN: ${b.bin})`));
}

Java

var banks = client.bank.getBanks();
if (banks.isSuccess()) {
    banks.getData().forEach(b -> System.out.println(b));
}

C#

var banks = await client.Bank.GetBanksAsync();
if (banks.IsSuccess)
    foreach (var b in banks.Data!) Console.WriteLine($"{b.ShortName} (BIN: {b.Bin})");

PHP

$banks = $client->bank->getBanks();
if ($banks->isSuccess()) {
    foreach ($banks->getData() as $b) echo "{$b->shortName} (BIN: {$b->bin})\n";
}

Tạo Deep Link thanh toán

Node.js

const deepLink = await client.deepLink.generate({
  vaAccountNumber: '123456789',
  amount: 150000,
  orderId: 'ORD-001',
  description: 'Thanh toán đơn hàng ORD-001',
});
if (isSuccessResponse(deepLink)) {
  console.log('Deep Link:', deepLink.data);
}

Java

var req = new OpenApiDeepLinkDto();
req.setVaAccountNumber("123456789");
req.setAmount(150000L);
req.setOrderId("ORD-001");
req.setDescription("Thanh toán đơn hàng ORD-001");

var deepLink = client.deepLink.generate(req);
if (deepLink.isSuccess()) {
    System.out.println("Deep Link: " + deepLink.getData());
}

C#

var deepLink = await client.DeepLink.GenerateAsync(new OpenApiDeepLinkDto
{
    VaAccountNumber = "123456789",
    Amount = 150000,
    OrderId = "ORD-001",
    Description = "Thanh toán đơn hàng ORD-001",
});
if (deepLink.IsSuccess) Console.WriteLine($"Deep Link: {deepLink.Data}");

PHP

$deepLink = $client->deepLink->generate(
    vaAccountNumber: '123456789',
    amount: 150000,
    orderId: 'ORD-001',
    description: 'Thanh toán đơn hàng ORD-001',
);
if ($deepLink->isSuccess()) echo "Deep Link: {$deepLink->getData()}\n";

---

Bước tiếp theo

• Xác thực Webhook — Xử lý thông báo giao dịch từ Tingee
• Tham chiếu API — Danh sách đầy đủ tất cả các methods