Khởi tạo lệnh chi hộ

POST

URLhttps://open-api.tingee.vn/v1/direct-link/create-transfer

Tạo lệnh chi hộ thanh toán xử lý thẳng (dành cho luồng VietinBank)

💡 Lưu ý về cơ chế xử lý giao dịch (VietinBank)

Đối với VietinBank, lệnh chi hộ đơn sẽ được Ngân hàng xử lý ngay sau khi tạo lệnh thành công. Tuy nhiên, đối với giao dịch chi lô, trạng thái lệnh chi ban đầu sẽ là PENDING và Ngân hàng sẽ tiếp tục xử lý hạch toán sau đó. Khách hàng cần gọi API truy vấn thông tin giao dịch để cập nhật kết quả xử lý cuối cù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)

Body Parameter

Trường	Kiểu	Bắt buộc	Mô tả
bankBin	string	✓	Mã BIN ngân hàng. Truyền cố định 970415 (Mã BIN của VietinBank)
senderAccountNumber	string	✓	Số tài khoản thanh toán (trích nợ)
senderAccountName	string	✓	Tên chủ tài khoản thanh toán.
transactionType	string	✓	Loại giao dịch - in-bank : Nội bộ ngân hàng - fast-out: Chuyển nhanh NAPAS 247 - regular-out: Chuyển thường liên ngân hàng
feeMethod	string	✓	Cách thức thu phí - O : Tài khoản thanh toán chịu phí - B: Tài khoản nhận tiền chịu phí
currency	string	✕	Loại tiền tệ hạch toán của tài khoản thanh toán (mặc định: VND)
records	array	✓	Danh sách bản ghi giao dịch cần tạo - Lệnh chi đơn: mảng gồm 1 phần tử - Lệnh chi lô: mảng gồm n phần tử

Chi tiết phần tử trong records

Trường	Kiểu	Bắt buộc	Mô tả
requestId	string	✓	Mã tham chiếu giao dịch do đối tác tự sinh, dùng để đối chiếu kết quả. Phải là duy nhất với mỗi giao dịch
receiverAccountNumber	string	✓	Số tài khoản của người nhận tiền
receiverAccountName	string	✓	Tên chủ tài khoản người nhận (không dấu, viết IN HOA)
amount	number	✓	Số tiền giao dịch
receiverBankBin	string	✓	Mã BIN ngân hàng nhận tiền. Xem tại Danh sách ngân hàng hỗ trợ
remark	string	✓	Nội dung chuyển tiền / diễn giải giao dịch
receiverCurrency	string	✕	Loại tiền tệ của tài khoản người nhận (mặc định: VND)

Payload Request mẫu

Dưới đây là các cấu trúc Payload mẫu cho lệnh chi đơn và chi lô. Bạn có thể click chọn từng Tab dưới đây, toàn bộ Ví dụ mã nguồn và Response mẫu bên dưới sẽ tự động đồng bộ theo kịch bản mà bạn chọn!

Chi đơn

{
  "bankBin": "970415",
  "senderAccountNumber": "117000107563",
  "senderAccountName": "Customer Title 1",
  "transactionType": "in-bank",
  "feeMethod": "O",
  "records": [
    {
      "requestId": "TRANS_0611_A03",
      "receiverAccountNumber": "103000614434",
      "receiverAccountName": "CUSTOMER TITLE 1",
      "amount": 100000,
      "receiverBankBin": "970415",
      "remark": "thanh toán"
    }
  ]
}

Chi lô

{
  "bankBin": "970415",
  "senderAccountNumber": "117000107563",
  "senderAccountName": "Customer Title 1",
  "transactionType": "in-bank",
  "feeMethod": "O",
  "records": [
    {
      "requestId": "TRANS_0611_A01",
      "receiverAccountNumber": "103000614434",
      "receiverAccountName": "CUSTOMER TITLE 1",
      "amount": 100000,
      "receiverBankBin": "970415",
      "remark": "thanh toán"
    },
    {
      "requestId": "TRANS_0611_A02",
      "receiverAccountNumber": "115000070017",
      "receiverAccountName": "Cty Huyen Trang Sua ten",
      "amount": 100000,
      "receiverBankBin": "970415",
      "remark": "thanh toán"
    }
  ]
}

Ví dụ mã nguồn

cURL

Chi đơn

curl --location --request POST 'https://open-api.tingee.vn/v1/direct-link/create-transfer' \
--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' \
--data '{
"bankBin": "970415",
"senderAccountNumber": "117000107563",
"senderAccountName": "Customer Title 1",
"transactionType": "in-bank",
"feeMethod": "O",
"records": [
  {
    "requestId": "TRANS_0611_A03",
    "receiverAccountNumber": "103000614434",
    "receiverAccountName": "CUSTOMER TITLE 1",
    "amount": 100000,
    "receiverBankBin": "970415",
    "remark": "thanh toán"
  }
]
}'

Chi lô

curl --location --request POST 'https://open-api.tingee.vn/v1/direct-link/create-transfer' \
--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' \
--data '{
"bankBin": "970415",
"senderAccountNumber": "117000107563",
"senderAccountName": "Customer Title 1",
"transactionType": "in-bank",
"feeMethod": "O",
"records": [
  {
    "requestId": "TRANS_0611_A01",
    "receiverAccountNumber": "103000614434",
    "receiverAccountName": "CUSTOMER TITLE 1",
    "amount": 100000,
    "receiverBankBin": "970415",
    "remark": "thanh toán"
  },
  {
    "requestId": "TRANS_0611_A02",
    "receiverAccountNumber": "115000070017",
    "receiverAccountName": "Cty Huyen Trang Sua ten",
    "amount": 100000,
    "receiverBankBin": "970415",
    "remark": "thanh toán"
  }
]
}'

NestJS

Chi đơn

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 body = {
"bankBin": "970415",
"senderAccountNumber": "117000107563",
"senderAccountName": "Customer Title 1",
"transactionType": "in-bank",
"feeMethod": "O",
"records": [
  {
    "requestId": "TRANS_0611_A03",
    "receiverAccountNumber": "103000614434",
    "receiverAccountName": "CUSTOMER TITLE 1",
    "amount": 100000,
    "receiverBankBin": "970415",
    "remark": "thanh toán"
  }
]
};
const message = `${timestamp}:${JSON.stringify(body)}`;
const signature = createHmac('sha512', secretKey).update(message).digest('hex');

const res = await axios({
  method: 'POST',
  url: 'https://open-api.tingee.vn/v1/direct-link/create-transfer',
  data: body,
  headers: {
    "x-client-id": "YOUR_CLIENT_ID",
    "x-request-timestamp": timestamp,
    "x-signature": signature,
    "Content-Type": "application/json",
  }
});

console.log(res.data);
}

Chi lô

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 body = {
"bankBin": "970415",
"senderAccountNumber": "117000107563",
"senderAccountName": "Customer Title 1",
"transactionType": "in-bank",
"feeMethod": "O",
"records": [
  {
    "requestId": "TRANS_0611_A01",
    "receiverAccountNumber": "103000614434",
    "receiverAccountName": "CUSTOMER TITLE 1",
    "amount": 100000,
    "receiverBankBin": "970415",
    "remark": "thanh toán"
  },
  {
    "requestId": "TRANS_0611_A02",
    "receiverAccountNumber": "115000070017",
    "receiverAccountName": "Cty Huyen Trang Sua ten",
    "amount": 100000,
    "receiverBankBin": "970415",
    "remark": "thanh toán"
  }
]
};
const message = `${timestamp}:${JSON.stringify(body)}`;
const signature = createHmac('sha512', secretKey).update(message).digest('hex');

const res = await axios({
  method: 'POST',
  url: 'https://open-api.tingee.vn/v1/direct-link/create-transfer',
  data: body,
  headers: {
    "x-client-id": "YOUR_CLIENT_ID",
    "x-request-timestamp": timestamp,
    "x-signature": signature,
    "Content-Type": "application/json",
  }
});

console.log(res.data);
}

C#

Chi đơn

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 bodyJson = "{"bankBin":"970415","senderAccountNumber":"117000107563","senderAccountName":"Customer Title 1","transactionType":"in-bank","feeMethod":"O","records":[{"requestId":"TRANS_0611_A03","receiverAccountNumber":"103000614434","receiverAccountName":"CUSTOMER TITLE 1","amount":100000,"receiverBankBin":"970415","remark":"thanh toán"}]}";
      var message = $"{timestamp}:{bodyJson}";
      var signature = CreateHmacSha512(secretKey, message);

      var request = new HttpRequestMessage(HttpMethod.Post, "https://open-api.tingee.vn/v1/direct-link/create-transfer");
      request.Headers.Add("x-signature", signature);
      request.Headers.Add("x-request-timestamp", timestamp);
      request.Headers.Add("x-client-id", "YOUR_CLIENT_ID");
      request.Content = new StringContent(bodyJson, Encoding.UTF8, "application/json");

      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();
  }
}

Chi lô

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 bodyJson = "{"bankBin":"970415","senderAccountNumber":"117000107563","senderAccountName":"Customer Title 1","transactionType":"in-bank","feeMethod":"O","records":[{"requestId":"TRANS_0611_A01","receiverAccountNumber":"103000614434","receiverAccountName":"CUSTOMER TITLE 1","amount":100000,"receiverBankBin":"970415","remark":"thanh toán"},{"requestId":"TRANS_0611_A02","receiverAccountNumber":"115000070017","receiverAccountName":"Cty Huyen Trang Sua ten","amount":100000,"receiverBankBin":"970415","remark":"thanh toán"}]}";
      var message = $"{timestamp}:{bodyJson}";
      var signature = CreateHmacSha512(secretKey, message);

      var request = new HttpRequestMessage(HttpMethod.Post, "https://open-api.tingee.vn/v1/direct-link/create-transfer");
      request.Headers.Add("x-signature", signature);
      request.Headers.Add("x-request-timestamp", timestamp);
      request.Headers.Add("x-client-id", "YOUR_CLIENT_ID");
      request.Content = new StringContent(bodyJson, Encoding.UTF8, "application/json");

      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

Chi đơn

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 bodyJson = "{"bankBin":"970415","senderAccountNumber":"117000107563","senderAccountName":"Customer Title 1","transactionType":"in-bank","feeMethod":"O","records":[{"requestId":"TRANS_0611_A03","receiverAccountNumber":"103000614434","receiverAccountName":"CUSTOMER TITLE 1","amount":100000,"receiverBankBin":"970415","remark":"thanh toán"}]}";
  String message = timestamp + ":" + bodyJson;
  String signature = hmacSha512(secretKey, message);

  HttpClient client = HttpClient.newHttpClient();
  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://open-api.tingee.vn/v1/direct-link/create-transfer"))
      .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")
      .POST(HttpRequest.BodyPublishers.ofString(bodyJson))
      .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();
}
}

Chi lô

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 bodyJson = "{"bankBin":"970415","senderAccountNumber":"117000107563","senderAccountName":"Customer Title 1","transactionType":"in-bank","feeMethod":"O","records":[{"requestId":"TRANS_0611_A01","receiverAccountNumber":"103000614434","receiverAccountName":"CUSTOMER TITLE 1","amount":100000,"receiverBankBin":"970415","remark":"thanh toán"},{"requestId":"TRANS_0611_A02","receiverAccountNumber":"115000070017","receiverAccountName":"Cty Huyen Trang Sua ten","amount":100000,"receiverBankBin":"970415","remark":"thanh toán"}]}";
  String message = timestamp + ":" + bodyJson;
  String signature = hmacSha512(secretKey, message);

  HttpClient client = HttpClient.newHttpClient();
  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://open-api.tingee.vn/v1/direct-link/create-transfer"))
      .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")
      .POST(HttpRequest.BodyPublishers.ofString(bodyJson))
      .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

Chi đơn

function makeApiRequest() {
  $timestamp = date("YmdHis") . substr((string)microtime(true), -3);
  $secretKey = "YOUR_SECRET_KEY";
  $jsonBody = '{"bankBin":"970415","senderAccountNumber":"117000107563","senderAccountName":"Customer Title 1","transactionType":"in-bank","feeMethod":"O","records":[{"requestId":"TRANS_0611_A03","receiverAccountNumber":"103000614434","receiverAccountName":"CUSTOMER TITLE 1","amount":100000,"receiverBankBin":"970415","remark":"thanh toán"}]}';
  $message = $timestamp . ":" . $jsonBody;
  $signature = hash_hmac("sha512", $message, $secretKey);

  $ch = curl_init();
  curl_setopt_array($ch, [
      CURLOPT_URL => "https://open-api.tingee.vn/v1/direct-link/create-transfer",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_POSTFIELDS => $jsonBody,
      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();

Chi lô

function makeApiRequest() {
  $timestamp = date("YmdHis") . substr((string)microtime(true), -3);
  $secretKey = "YOUR_SECRET_KEY";
  $jsonBody = '{"bankBin":"970415","senderAccountNumber":"117000107563","senderAccountName":"Customer Title 1","transactionType":"in-bank","feeMethod":"O","records":[{"requestId":"TRANS_0611_A01","receiverAccountNumber":"103000614434","receiverAccountName":"CUSTOMER TITLE 1","amount":100000,"receiverBankBin":"970415","remark":"thanh toán"},{"requestId":"TRANS_0611_A02","receiverAccountNumber":"115000070017","receiverAccountName":"Cty Huyen Trang Sua ten","amount":100000,"receiverBankBin":"970415","remark":"thanh toán"}]}';
  $message = $timestamp . ":" . $jsonBody;
  $signature = hash_hmac("sha512", $message, $secretKey);

  $ch = curl_init();
  curl_setopt_array($ch, [
      CURLOPT_URL => "https://open-api.tingee.vn/v1/direct-link/create-transfer",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_POSTFIELDS => $jsonBody,
      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

Chi đơn

{
    "code": "00",
    "message": "Success",
    "data": {
        "totalRecords": 1,
        "processedRecords": 1,
        "batchId": null,
        "records": [
            {
                "status": "SUCCESS",
                "requestId": "TRANS_0611_A03",
                "transactionId": "3NGiS-89m8nkbW5",
                "message": "Giao dich hach toan thanh cong"
            }
        ]
    }
}

Chi lô

{
    "code": "00",
    "message": "Success",
    "data": {
        "totalRecords": 2,
        "processedRecords": 0,
        "batchId": "7CB875795D6B2F3374D3B489B09CAA92",
        "records": [
            {
                "status": "PENDING",
                "requestId": "TRANS_0611_A01",
                "transactionId": null,
                "message": "Dang pending cho xu ly hach toan"
            },
            {
                "status": "PENDING",
                "requestId": "TRANS_0611_A02",
                "transactionId": null,
                "message": "Dang pending cho xu ly hach toan"
            }
        ]
    }
}

Cấu trúc Response data

Trường	Kiểu	Mô tả
batchId	string	Mã lô giao dịch (chỉ trả về khi lệnh chi lô được tiếp nhận).
totalRecords	number	Tổng số lượng giao dịch trong lệnh chi.
processedRecords	number	Số lượng giao dịch đã được xử lý xong.
records	array	Danh sách kết quả chi tiết từng giao dịch.

Chi tiết phần tử trong data.records

Trường	Kiểu	Mô tả
requestId	string	Mã tham chiếu giao dịch đã gửi lên.
status	string	Trạng thái giao dịch (VD: SUCCESS, PENDING).
transactionId	string	Mã giao dịch trên hệ thống ngân hàng (nếu có).
message	string	Thông báo chi tiết hoặc diễn giải trạng thái.

---

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.