Phiên bản: 1.2.2 (Latest)

Truy vấn thông tin người hưởng (BIDV, BaoKim)

GET

URLhttps://open-api.tingee.vn/v1/direct-link/financial-utility/account-inquiry

Truy vấn thông tin tài khoản hưởng

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 thực hiện truy vấn. Truyền 970418 (BIDV), 970415 (VietinBank) hoặc BAOKIM (BaoKim).
`creditAccountNumber`	string	✓	Số tài khoản / số thẻ / số ví người hưởng cần truy vấn.
`creditBankBin`	string	~	Mã BIN ngân hàng của người hưởng. Xem tại Danh sách ngân hàng hỗ trợ. Bắt buộc, trừ trường hợp BAOKIM với `accountType = WALLET`.
`creditBankBranchCode`	string	✕	Mã chi nhánh ngân hàng của người hưởng. Chỉ áp dụng với VietinBank.
`role`	string	~	Vai trò người dùng: `Maker` hoặc `Checker`. Bắt buộc với BIDV.
`accountType`	string	~	Loại tài khoản người hưởng (chỉ áp dụng với BAOKIM): - `ACCOUNT`: Số tài khoản ngân hàng - `CARD`: Số thẻ - `WALLET`: Ví BaoKim (không cần `creditBankBin`) Giá trị `ID`, `PHONE` cũng được chấp nhận và xử lý như `ACCOUNT`. Bắt buộc với BAOKIM.
`walletId`	string	~	Tên đăng nhập (username) ví BaoKim của doanh nghiệp đã liên kết với TINGEE (ví dùng để tra cứu). Bắt buộc với BAOKIM.

Ví dụ mã nguồn

cURL
NestJS
C#
Java
PHP

curl --location --request GET 'https://open-api.tingee.vn/v1/direct-link/financial-utility/account-inquiry?bankBin=970418&role=Maker&creditBankBin=970418&creditAccountNumber=1234567890' \
--header 'accept: application/json' \
--header 'x-client-id: YOUR_CLIENT_ID' \
--header 'x-request-timestamp: 20240509154004003' \
--header 'x-signature: YOUR_SIGNATURE'

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

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

// Timestamp theo múi giờ UTC+7, định dạng yyyyMMddHHmmssSSS
function getTimestamp() {
    return new Date(Date.now() + 7 * 60 * 60 * 1000)
        .toISOString()
        .replace(/[-:TZ.]/g, "")
        .slice(0, 17);
}

async function directLinkFinancialUtilityAccountInquiry() {
    const body = {}; // Request không có body: ký trên chuỗi "{}"

    const params = {
        bankBin: "970418",
        role: "Maker",
        creditBankBin: "970418",
        creditAccountNumber: "1234567890",
    };

    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-link/financial-utility/account-inquiry",
        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);
}

directLinkFinancialUtilityAccountInquiry();

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 không có body: ký trên chuỗi "{}"

        // Timestamp theo múi giờ UTC+7, định dạng 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-link/financial-utility/account-inquiry?bankBin=970418&role=Maker&creditBankBin=970418&creditAccountNumber=1234567890");
        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();
    }
}

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 {
        // JSON minified, giống kết quả JSON.stringify(). Request không có body: ký trên chuỗi "{}"
        String bodyJson = "{}";

        // Timestamp theo múi giờ UTC+7, định dạng 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-link/financial-utility/account-inquiry?bankBin=970418&role=Maker&creditBankBin=970418&creditAccountNumber=1234567890"))
                .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
$clientId = "YOUR_CLIENT_ID";
$secretKey = "YOUR_SECRET_KEY";

$bodyJson = "{}"; // Request không có body: ký trên chuỗi "{}"

// Timestamp theo múi giờ UTC+7, định dạng 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-link/financial-utility/account-inquiry?bankBin=970418&role=Maker&creditBankBin=970418&creditAccountNumber=1234567890",
    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);

Response mẫu

{
  "code": "00",
  "message": "Success",
  "data": {
    "creditAccountNumber": "1234567890",
    "creditAccountName": "NGUYEN VAN A",
    "creditBankBin": "970418"
  }
}

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`	object	Thông tin người hưởng. Riêng BAOKIM: nếu BaoKim trả về nhiều kết quả, `data` là mảng các đối tượng có cùng cấu trúc bên dưới.
`data.creditAccountNumber`	string	Số tài khoản / số thẻ / số ví người hưởng.
`data.creditAccountName`	string	Tên chủ tài khoản người hưởng.
`data.creditBankBin`	string	Mã BIN ngân hàng người hưởng.
`data.creditPhoneNumber`	string	Số điện thoại người hưởng (chỉ BAOKIM, nếu có; đã chuyển về dạng `0xxxxxxxxx`).

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

Code	Mô tả	Hướng xử lý
`1077`	Phiên ủy quyền BIDV của vai trò (role) đã hết hạn hoặc chưa được cấp	Gọi Lấy đường dẫn xác thực với đúng `role` để ủy quyền lại, sau đó tra cứu lại.
`1086`	Ví BAOKIM của Merchant chưa được cấu hình	Kiểm tra `walletId` đã liên kết với TINGEE; nếu vẫn lỗi, liên hệ TINGEE để hoàn tất cấu hình ví.
`1021`	Ngân hàng không được hỗ trợ cho API này	Kiểm tra `bankBin`; chỉ hỗ trợ BIDV, VietinBank, OCB và BAOKIM.
`90`, `91`, `92`, `97`	Lỗi xác thực request (timestamp, client-id, chữ ký)	Xem Mã lỗi hệ thống.
`Others`	Lỗi khác	Xem Danh sách mã lỗi.

Header Request​

Query Parameters​

Ví dụ mã nguồn​

Response mẫu​

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

Header Request

Query Parameters

Ví dụ mã nguồn

Response mẫu

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