Lịch sử giao dịch tài khoản thanh toán

GET

URLhttps://open-api.tingee.vn/v1/direct-link/account-statement/payment-transaction-history

Lịch sử giao dịch thanh toán

Header Request

Header	Bắt buộc	Mô tả
Content-Type	✓	application/json
x-client-id	✓	Mã định danh của đối tác do TINGEE cung cấp.
x-signature	✓	Chữ ký xác thực HMAC SHA512.
x-request-timestamp	✓	Thời gian gửi request (format: yyyyMMddHHmmssSSS, múi giờ UTC+7)

Query Parameters

Trường	Kiểu	Bắt buộc	Mô tả
bankBin	string	✓	Mã BIN ngân hàng. Xem tại Danh sách ngân hàng hỗ trợ.
role	string	~	Vai trò người dùng (chỉ yêu cầu đối với ngân hàng BIDV: Maker, Checker).
accountNumber	string	✓	Số tài khoản ngân hàng
startDate	string	✕	Thời gian bắt đầu tìm kiếm (yyyy-MM-dd)
endDate	string	✕	Thời gian kết thúc tìm kiếm (yyyy-MM-dd)
moreRecordIndicator	string	✕	Cờ báo hiệu vẫn còn dữ liệu ở trang tiếp theo (Y/N)
postingDate	string	✕	Ngày hạch toán giao dịch trên hệ thống
postingOrder	string	✕	Thứ tự hạch toán giao dịch
balanceAfterTxn	string	✕	Số dư tài khoản sau giao dịch
totalRecords	number	✕	Tổng số lượng bản ghi trên toàn hệ thống

Ví dụ mã nguồn

cURL

curl --location --request GET 'https://open-api.tingee.vn/v1/direct-link/account-statement/payment-transaction-history' \
--header 'accept: application/json' \
--header 'x-signature: YOUR_SIGNATURE' \
--header 'x-request-timestamp: 20251110175110111' \
--header 'x-client-id: YOUR_CLIENT_ID' \
--header 'Content-Type: application/json'

NestJS

import axios from "axios";
import { createHmac } from "crypto";
import { format } from 'date-fns';

async function makeRequest() {
const timestamp = format(new Date(), "yyyyMMddHHmmssSSS");
const secretKey = "YOUR_SECRET_KEY";
const message = `${timestamp}`;
const signature = createHmac('sha512', secretKey).update(message).digest('hex');

const res = await axios({
  method: 'GET',
  url: 'https://open-api.tingee.vn/v1/direct-link/account-statement/payment-transaction-history',
  data: null,
  headers: {
    "x-client-id": "YOUR_CLIENT_ID",
    "x-request-timestamp": timestamp,
    "x-signature": signature,
    "Content-Type": "application/json",
  }
});

console.log(res.data);
}

C#

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

public class TingeeApiExample
{
  private static readonly HttpClient client = new HttpClient();

  public static async Task Main()
  {
      var timestamp = DateTime.Now.ToString("yyyyMMddHHmmssfff");
      var secretKey = "YOUR_SECRET_KEY";
      var message = timestamp;
      var signature = CreateHmacSha512(secretKey, message);

      var request = new HttpRequestMessage(HttpMethod.Get, "https://open-api.tingee.vn/v1/direct-link/account-statement/payment-transaction-history");
      request.Headers.Add("x-signature", signature);
      request.Headers.Add("x-request-timestamp", timestamp);
      request.Headers.Add("x-client-id", "YOUR_CLIENT_ID");

      var response = await client.SendAsync(request);
      string result = await response.Content.ReadAsStringAsync();
      Console.WriteLine(result);
  }

  private static string CreateHmacSha512(string key, string message)
  {
      using var hmac = new HMACSHA512(Encoding.UTF8.GetBytes(key));
      var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(message));
      return BitConverter.ToString(hash).Replace("-", "").ToLower();
  }
}

Java

import java.net.http.*;
import java.net.URI;
import java.nio.charset.StandardCharsets;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

public class TingeeApiExample {
public static void main(String[] args) throws Exception {
  String secretKey = "YOUR_SECRET_KEY";
  String timestamp = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMddHHmmssSSS"));
  String message = timestamp;
  String signature = hmacSha512(secretKey, message);

  HttpClient client = HttpClient.newHttpClient();
  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://open-api.tingee.vn/v1/direct-link/account-statement/payment-transaction-history"))
      .header("accept", "application/json")
      .header("x-signature", signature)
      .header("x-request-timestamp", timestamp)
      .header("x-client-id", "YOUR_CLIENT_ID")
      .header("Content-Type", "application/json")
      .GET()
      .build();

  HttpResponse<String> response = client.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");
    SecretKeySpec secretKeySpec = new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "HmacSHA512");
    mac.init(secretKeySpec);
    byte[] hash = mac.doFinal(data.getBytes(StandardCharsets.UTF_8));
    return toHex(hash);
}

private static String toHex(byte[] bytes) {
    StringBuilder hex = new StringBuilder(bytes.length * 2);
    for (byte b : bytes) {
        hex.append(String.format("%02x", b));
    }
    return hex.toString();
}
}

PHP

function makeApiRequest() {
  $timestamp = date("YmdHis") . substr((string)microtime(true), -3);
  $secretKey = "YOUR_SECRET_KEY";
  $message = $timestamp;
  $signature = hash_hmac("sha512", $message, $secretKey);

  $ch = curl_init();
  curl_setopt_array($ch, [
      CURLOPT_URL => "https://open-api.tingee.vn/v1/direct-link/account-statement/payment-transaction-history",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
          "Accept: application/json",
          "Content-Type: application/json",
          "x-client-id: YOUR_CLIENT_ID",
          "x-request-timestamp: " . $timestamp,
          "x-signature: " . $signature
      ]
  ]);

  $response = curl_exec($ch);
  curl_close($ch);
  echo $response;
}
makeApiRequest();

Response mẫu

{
  "code": "00",
  "message": "Success",
  "data": {
    "items": [
      {
        "coreRefNo": "REF001",
        "transTime": "2025-01-01 10:00:00",
        "debitAmount": 1000000,
        "creditAmount": 0,
        "remark": "Thanh toan hoa don",
        "nextRUNBAL": "9000000",
        "postingDate": "2025-01-01",
        "postingOrder": "001",
        "moreRecordIndicator": "N"
      }
    ],
    "total": 1
  }
}

Trường	Kiểu	Mô tả
code	string	Mã kết quả (00 = Thành công).
message	string	Thông điệp phản hồi.
data.items	array	Danh sách giao dịch thanh toán.
data.items[].coreRefNo	string	Mã tham chiếu giao dịch.
data.items[].transTime	string	Thời gian giao dịch.
data.items[].debitAmount	number	Số tiền ghi nợ.
data.items[].creditAmount	number	Số tiền ghi có.
data.items[].remark	string	Nội dung giao dịch.
data.items[].nextRUNBAL	string	Số dư sau giao dịch.
data.items[].postingDate	string	Ngày hạch toán.
data.items[].postingOrder	string	Thứ tự hạch toán.
data.items[].moreRecordIndicator	string	Còn bản ghi tiếp theo (Y/N).
data.total	number	Tổng số giao dịch.

---

Mã lỗi thường gặp

Code	Mô tả	Hướng xử lý
90	Sai format timestamp	Kiểm tra format yyyyMMddHHmmssSSS.
91	Request quá hạn	Kiểm tra thời gian gửi request.
97	Sai chữ ký	Kiểm tra lại Secret Key và logic tạo Signature.
Others	Lỗi khác	Xem Danh sách mã lỗi.