Quickstart

This guide helps you make your first API call with the Tingee SDK in just a few minutes.

Before you start

• You have installed the SDK for your language
• You have a clientId and secretKey from the Tingee Dashboard

---

1. Initialize the 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', // use 'uat' for testing, 'production' when going 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. Make your first API call

Example: get the list of Merchants.

Node.js

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

if (isSuccessResponse(result)) {
  console.log('Merchant list:');
  result.data.items.forEach(m => console.log(` - ${m.name}`));
} else {
  console.error(`Error ${result.code}: ${result.message}`);
}

Java

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

if (result.isSuccess()) {
    System.out.println("Merchant list:");
    result.getData().getItems().forEach(m -> System.out.println(" - " + m));
} else {
    System.err.println("Error " + result.getCode() + ": " + result.getMessage());
}

C#

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

if (result.IsSuccess)
{
    Console.WriteLine("Merchant list:");
    foreach (var m in result.Data!.Items!)
        Console.WriteLine($" - {m.Name}");
}
else
{
    Console.Error.WriteLine($"Error {result.Code}: {result.Message}");
}

PHP

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

if ($result->isSuccess()) {
    echo "Merchant list:\n";
    foreach ($result->getData()->items as $m) {
        echo " - {$m->name}\n";
    }
} else {
    echo "Error {$result->getCode()}: {$result->getMessage()}\n";
}

---

3. Handle the response

The SDK returns a TingeeApiResponse for every API call:

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

The SDK does not throw exceptions

When code !== '00', the SDK does not throw an exception. Check code yourself or use a helper:

Node.js

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

if (isSuccessResponse(result)) {
  // code === '00' → handle result.data
} else if (isErrorResponse(result)) {
  // code !== '00' → handle the error
  console.error(`${result.code}: ${result.message}`);
}

Java

if (result.isSuccess()) {
    // code == "00" → handle result.getData()
} else {
    // code != "00" → handle the error
    System.err.println(result.getCode() + ": " + result.getMessage());
}

C#

if (result.IsSuccess)
{
    // Code == "00" → handle result.Data
}
else
{
    // Code != "00" → handle the error
    Console.Error.WriteLine($"{result.Code}: {result.Message}");
}

PHP

if ($result->isSuccess()) {
    // code === '00' → handle $result->getData()
} else {
    // code !== '00' → handle the error
    echo $result->getCode() . ': ' . $result->getMessage();
}

---

4. More examples

List supported banks

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";
}

Create a payment Deep Link

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";

---

Next steps

• Webhook verification — Handle transaction notifications from Tingee
• API reference — Full list of all methods