Query transaction history

Use this API to query a customer's transaction history by time range or with pagination.

Use it when you want to query and sync the transaction history of customer accounts registered for the Direct Debit service.

GET

URLhttps://open-api.tingee.vn/v1/direct-debit/get-paging-transactions

Get the list of completed payment transactions, with time filtering and pagination.

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
subscriptionId	string	✓	ID of the linked bank account (UUID).
tokenRef	string	✓	Reference code of the customer's account.
startTime	string	✕	Start time (yyyy-MM-dd HH:mm:ss). Default: 30 days before the API call. The system filters from the start of the startTime day.
endTime	string	✕	End time (yyyy-MM-dd HH:mm:ss). Default: the time of the API call. The system filters up to the end of the endTime day. The startTime – endTime range is at most 30 days.
skipCount	number	✕	Number of transactions to skip (default: 0).
maxResultCount	number	✕	Number of transactions to return (default: 10).

Code samples

cURL

curl --location --request GET 'https://open-api.tingee.vn/v1/direct-debit/get-paging-transactions?subscriptionId=89188e53-eba3-40fa-9323-04422ced3637&tokenRef=TKN-12345678&startTime=2025-12-16%2012%3A20%3A49&endTime=2026-01-15%2012%3A20%3A49&skipCount=0&maxResultCount=10' \
--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 directDebitGetPagingTransactions() {
    const body = {}; // Request has no body: sign the string "{}"

    const params = {
        subscriptionId: "89188e53-eba3-40fa-9323-04422ced3637",
        tokenRef: "TKN-12345678",
        startTime: "2025-12-16 12:20:49",
        endTime: "2026-01-15 12:20:49",
        skipCount: "0",
        maxResultCount: "10",
    };

    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-paging-transactions",
        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);
}

directDebitGetPagingTransactions();

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-paging-transactions?subscriptionId=89188e53-eba3-40fa-9323-04422ced3637&tokenRef=TKN-12345678&startTime=2025-12-16%2012%3A20%3A49&endTime=2026-01-15%2012%3A20%3A49&skipCount=0&maxResultCount=10");
        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-paging-transactions?subscriptionId=89188e53-eba3-40fa-9323-04422ced3637&tokenRef=TKN-12345678&startTime=2025-12-16%2012%3A20%3A49&endTime=2026-01-15%2012%3A20%3A49&skipCount=0&maxResultCount=10"))
                .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-paging-transactions?subscriptionId=89188e53-eba3-40fa-9323-04422ced3637&tokenRef=TKN-12345678&startTime=2025-12-16%2012%3A20%3A49&endTime=2026-01-15%2012%3A20%3A49&skipCount=0&maxResultCount=10",
    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": {
    "totalCount": 1,
    "items": [
      {
        "transactionId": "550760e0-1cc2-44b9-85ba-eb318e228b4f",
        "code": "FT123372233",
        "bankName": "VCB",
        "bankBin": "970436",
        "amount": "150000",
        "content": "Thanh toan don hang #12345",
        "accountNumber": "0123456789",
        "transactionDate": "2026-01-15T05:20:49.000Z",
        "subscriptionId": "89188e53-eba3-40fa-9323-04422ced3637",
        "tokenRef": "TKN-12345678",
        "status": "success",
        "additionalData": {
          "billNumber": "HD123456"
        }
      }
    ]
  }
}

Field	Type	Description
code	string	Response code (00 means success).
message	string	Detailed message.
data.totalCount	number	Total number of transactions found.
data.items	array	List of successful transactions, sorted by transactionDate in descending order.
data.items[].transactionId	string	ID of the debit transaction on TINGEE (the requestId you sent when calling Pay a bill).
data.items[].code	string	Transaction code at the debit gateway.
data.items[].bankName	string	Bank code (e.g. VCB).
data.items[].bankBin	string	Bank BIN.
data.items[].amount	string	Transaction amount (VND).
data.items[].content	string	Payment description.
data.items[].accountNumber	string	Debited account number.
data.items[].transactionDate	string	Transaction time (ISO 8601).
data.items[].subscriptionId	string	ID of the linked bank account.
data.items[].tokenRef	string	Reference code of the customer's account.
data.items[].status	string	Transaction status (the API only returns success transactions).
data.items[].additionalData	object	Additional data you sent when calling Pay a bill.

---

Common error codes

Code	Description	How to handle
1126	The query time range is too large (more than 30 days)	Keep startTime – endTime within 30 days; split the range and make several calls if needed.
90, 91, 92, 97	Request authentication error (timestamp, client-id, signature)	See System error codes.
Others	Other errors	See Error codes.