Query account status

Use this API to query the link status of an account.

Use it when you want to query the status of registered customer accounts and sync it with the data on Tingee.

GET

URLhttps://open-api.tingee.vn/v1/direct-debit/get-subscription-status

Get the details and current status (active/inactive) of a linked account.

Header Request

Header	Required	Description
Content-Type	✓	application/json
x-client-id	✓	Partner identifier issued by TINGEE.
x-signature	✓	HMAC SHA512 authentication signature. See How to generate the signature.
x-request-timestamp	✓	Time the request is sent (format: yyyyMMddHHmmssSSS, UTC+7)

Query Parameter

Field	Type	Required	Description
requestId	string	~	ID of the request used when registering (UUID). Send requestId, or the subscriptionId + tokenRef pair.
subscriptionId	string	~	ID of the linked bank account (UUID). Required when requestId is not sent.
tokenRef	string	~	Reference code of the customer's account. Required when requestId is not sent.

Code samples

cURL

curl --location --request GET 'https://open-api.tingee.vn/v1/direct-debit/get-subscription-status?requestId=550760e0-1cc2-44b9-85ba-eb318e228b4f&subscriptionId=89188e53-eba3-40fa-9323-04422ced3637&tokenRef=TKN-12345678' \
--header 'accept: application/json' \
--header 'x-client-id: YOUR_CLIENT_ID' \
--header 'x-request-timestamp: 20240509154004003' \
--header 'x-signature: YOUR_SIGNATURE'

NestJS

import axios from "axios";
import { createHmac } from "crypto";

const CLIENT_ID = "YOUR_CLIENT_ID";
const SECRET_KEY = "YOUR_SECRET_KEY";

// Timestamp in UTC+7, format yyyyMMddHHmmssSSS
function getTimestamp() {
    return new Date(Date.now() + 7 * 60 * 60 * 1000)
        .toISOString()
        .replace(/[-:TZ.]/g, "")
        .slice(0, 17);
}

async function directDebitGetSubscriptionStatus() {
    const body = {}; // Request has no body: sign the string "{}"

    const params = {
        requestId: "550760e0-1cc2-44b9-85ba-eb318e228b4f",
        subscriptionId: "89188e53-eba3-40fa-9323-04422ced3637",
        tokenRef: "TKN-12345678",
    };

    const bodyJson = JSON.stringify(body);
    const timestamp = getTimestamp();
    const signature = createHmac("sha512", SECRET_KEY)
        .update(`${timestamp}:${bodyJson}`)
        .digest("hex");

    const res = await axios.request({
        method: "GET",
        url: "https://open-api.tingee.vn/v1/direct-debit/get-subscription-status",
        params,
        headers: {
            accept: "application/json",
            "Content-Type": "application/json",
            "x-client-id": CLIENT_ID,
            "x-request-timestamp": timestamp,
            "x-signature": signature,
        },
    });

    console.log(res.data);
}

directDebitGetSubscriptionStatus();

C#

using System;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;

public class Program
{
    private const string ClientId = "YOUR_CLIENT_ID";
    private const string SecretKey = "YOUR_SECRET_KEY";
    private static readonly HttpClient Client = new HttpClient();

    public static async Task Main()
    {
        var bodyJson = "{}"; // Request has no body: sign the string "{}"

        // Timestamp in UTC+7, format yyyyMMddHHmmssSSS
        var timestamp = DateTime.UtcNow.AddHours(7).ToString("yyyyMMddHHmmssfff");
        var signature = HmacSha512(SecretKey, $"{timestamp}:{bodyJson}");

        var request = new HttpRequestMessage(HttpMethod.Get, "https://open-api.tingee.vn/v1/direct-debit/get-subscription-status?requestId=550760e0-1cc2-44b9-85ba-eb318e228b4f&subscriptionId=89188e53-eba3-40fa-9323-04422ced3637&tokenRef=TKN-12345678");
        request.Headers.Add("accept", "application/json");
        request.Headers.Add("x-client-id", ClientId);
        request.Headers.Add("x-request-timestamp", timestamp);
        request.Headers.Add("x-signature", signature);

        var response = await Client.SendAsync(request);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }

    private static string HmacSha512(string key, string message)
    {
        using var hmac = new HMACSHA512(Encoding.UTF8.GetBytes(key));
        var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(message));
        return Convert.ToHexString(hash).ToLower();
    }
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.ZoneId;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class Main {
    private static final String CLIENT_ID = "YOUR_CLIENT_ID";
    private static final String SECRET_KEY = "YOUR_SECRET_KEY";

    public static void main(String[] args) throws Exception {
        // Minified JSON, same as JSON.stringify(). Request has no body: sign the string "{}"
        String bodyJson = "{}";

        // Timestamp in UTC+7, format yyyyMMddHHmmssSSS
        String timestamp = ZonedDateTime.now(ZoneId.of("Asia/Ho_Chi_Minh"))
                .format(DateTimeFormatter.ofPattern("yyyyMMddHHmmssSSS"));
        String signature = hmacSha512(SECRET_KEY, timestamp + ":" + bodyJson);

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://open-api.tingee.vn/v1/direct-debit/get-subscription-status?requestId=550760e0-1cc2-44b9-85ba-eb318e228b4f&subscriptionId=89188e53-eba3-40fa-9323-04422ced3637&tokenRef=TKN-12345678"))
                .header("accept", "application/json")
                .header("Content-Type", "application/json")
                .header("x-client-id", CLIENT_ID)
                .header("x-request-timestamp", timestamp)
                .header("x-signature", signature)
                .method("GET", HttpRequest.BodyPublishers.noBody())
                .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
                .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }

    private static String hmacSha512(String key, String data) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA512");
        mac.init(new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "HmacSHA512"));
        byte[] hash = mac.doFinal(data.getBytes(StandardCharsets.UTF_8));
        StringBuilder hex = new StringBuilder();
        for (byte b : hash) hex.append(String.format("%02x", b));
        return hex.toString();
    }
}

PHP

<?php
$clientId = "YOUR_CLIENT_ID";
$secretKey = "YOUR_SECRET_KEY";

$bodyJson = "{}"; // Request has no body: sign the string "{}"

// Timestamp in UTC+7, format yyyyMMddHHmmssSSS
$now = new DateTime("now", new DateTimeZone("Asia/Ho_Chi_Minh"));
$timestamp = $now->format("YmdHisv");
$signature = hash_hmac("sha512", $timestamp . ":" . $bodyJson, $secretKey);

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => "https://open-api.tingee.vn/v1/direct-debit/get-subscription-status?requestId=550760e0-1cc2-44b9-85ba-eb318e228b4f&subscriptionId=89188e53-eba3-40fa-9323-04422ced3637&tokenRef=TKN-12345678",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
        "Accept: application/json",
        "Content-Type: application/json",
        "x-client-id: " . $clientId,
        "x-request-timestamp: " . $timestamp,
        "x-signature: " . $signature,
    ],
]);

$response = curl_exec($ch);
if ($response === false) {
    echo "cURL Error: " . curl_error($ch);
} else {
    echo $response;
}
curl_close($ch);

Sample Response

{
  "code": "00",
  "message": "Success",
  "data": {
    "tokenRef": "TKN-12345678",
    "bankName": "VCB",
    "bankBin": "970436",
    "accountName": "NGUYEN VAN A",
    "accountNumber": "0123456789",
    "phone": "0974444479",
    "email": "nguyenvana@example.com",
    "confirmPaymentByEmail": true,
    "confirmEmail": "nguyenvana@example.com",
    "confirmPaymentByZalo": false,
    "confirmPhoneNumber": null,
    "customerKey": null,
    "status": "active",
    "lastModificationTime": "2026-01-15T05:20:49.000Z",
    "lastModifierUserId": null
  }
}

Field	Type	Description
code	string	Response code (00 means success).
message	string	Detailed message.
data.tokenRef	string	Reference code of the customer's account.
data.bankName	string	Bank code of the linked account (e.g. VCB).
data.bankBin	string	Bank BIN.
data.accountName	string	Account holder name.
data.accountNumber	string	Linked account number.
data.phone	string	Registered phone number.
data.email	string	Customer's email (if any).
data.confirmPaymentByEmail	boolean	true if the customer requires payment confirmation by Email.
data.confirmEmail	string	Email that receives payment confirmation requests.
data.confirmPaymentByZalo	boolean	true if the customer requires payment confirmation via Zalo.
data.confirmPhoneNumber	string	Phone number that receives payment confirmation requests via Zalo.
data.customerKey	string	Customer identifier key on TINGEE (if any).
data.status	string	Link status: active (active), inactive (inactive).
data.lastModificationTime	string	Last update time (ISO 8601).
data.lastModifierUserId	number	ID of the user who last updated it (if any).

---

Common error codes

Code	Description	How to handle
1067	Subscription not found	Check the requestId used when registering, or the subscriptionId + tokenRef pair.
90, 91, 92, 97	Request authentication error (timestamp, client-id, signature)	See System error codes.
Others	Other errors	See Error codes.