Tạo tài khoản ảo (VA)

API này dùng để tạo mới tài khoản ảo (Virtual Account - VA) cho Merchant, cho phép nhận thông báo biến động số dư và quản lý dòng tiền tách biệt.

PUBLIC SANDBOX — LIÊN KẾT NGÂN HÀNG

Trải nghiệm toàn bộ quy trình liên kết tài khoản và xác thực OTP với dữ liệu giả lập.

Thử trong Sandbox

POST

URLhttps://open-api.tingee.vn/v1/create-va

API khởi tạo yêu cầu tạo hoặc liên kết tài khoản ảo với ngân hàng. Kết quả trả về confirmId cần được dùng cho bước xác nhận tiếp theo.

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. Xem thêm tại Cách sinh chữ ký.
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ả
merchantId	number	✕	ID của Merchant (Bắt buộc nếu kết nối bằng tài khoản Master Merchant).
accountType	string	~	Loại tài khoản (personal-account, business-account, business-household-account). Bắt buộc khi kết nối với các ngân hàng ngoài BAOKIM
bankBin	string	✓	Mã BIN ngân hàng. Xem tại Danh sách ngân hàng hỗ trợ.
accountNumber	string	~	Số tài khoản ngân hàng muốn liên kết. Không bắt buộc với ngân hàng TPBank, VCB và MSB
accountName	string	~	Tên chủ tài khoản. Không bắt buộc với ngân hàng TPBank
identity	string	✕	GTTT của khách hàng (CMND/CCCD hoặc Mã số thuế).
mobile	string	~	Số điện thoại đăng ký (Tùy theo yêu cầu từng ngân hàng).
isNotifyAccountNumber	boolean	✕	true nếu muốn liên kết STK gốc, mặc định false để tạo STK ảo.
shopId	number	✕	ID cửa hàng. Nếu truyền tham số này, hệ thống sẽ gán VA được tạo vào cửa hàng tương ứng. Nếu để trống, hệ thống sẽ tự động tạo một cửa hàng mới khi tạo VA và gán VA vào cửa hàng mới đó. (ID cửa hàng sẽ được trả về trong response).
merchantName	string	✕	Tên cửa hàng muốn tạo mới (chỉ áp dụng trong trường hợp không truyền shopId).
name	string	✕	Tên dòng tiền.
transactionType	string	✕	Loại giao dịch đăng ký - credit: Giao dịch ghi có - debit: Giao dịch ghi nợ ( chỉ áp dụng với ngân hàng ACB ) Mặc định là credit
webhookUrl	string	✕	URL nhận thông báo đăng ký/hủy đăng ký tài khoản (Bắt buộc nếu tạo VA của ngân hàng TPBank hoặc VCB tài khoản Cá nhân).
walletId	string	~	ID Ví điện tử muốn tạo STK ảo (Bắt buộc khi sử dụng BAOKIM).

Ví dụ mã nguồn

cURL

curl --location --request POST 'https://open-api.tingee.vn/v1/create-va' \
--header 'accept: application/json' \
--header 'x-signature: YOUR_SIGNATURE' \
--header 'x-request-timestamp: 20250723142001111' \
--header 'x-client-id: YOUR_CLIENT_ID' \
--header 'Content-Type: application/json' \
--data '{
  "isNotifyAccountNumber": false,
  "accountType": "personal-account",
  "bankBin": "970418",
  "accountNumber": "0935926988",
  "accountName": "NGUYEN THI HUYEN",
  "identity": "040191014068",
  "mobile": "0123456789"
}'

NestJS

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

async function createVA() {
const body = {
  isNotifyAccountNumber: false,
  accountType: 'personal-account',
  bankBin: '970418',
  accountNumber: '0935926988',
  accountName: 'NGUYEN THI HUYEN',
  identity: '040191014068',
  mobile: '0123456789'
};

const timestamp = format(new Date(), "yyyyMMddHHmmssSSS");
const secretKey = "YOUR_SECRET_KEY";
const message = `${timestamp}:${JSON.stringify(body)}`;
const signature = createHmac('sha512', secretKey).update(message).digest('hex');

const res = await axios.post('https://open-api.tingee.vn/v1/create-va', body, {
  headers: {
    accept: 'application/json',
    'x-signature': signature,
    'x-request-timestamp': timestamp,
    'x-client-id': 'YOUR_CLIENT_ID',
    'Content-Type': 'application/json',
  },
});

console.log(res.data);
}

C#

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

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

  public static async Task Main()
  {
      var body = new {
          isNotifyAccountNumber = false,
          accountType = "personal-account",
          bankBin = "970418",
          accountNumber = "0935926988",
          accountName = "NGUYEN THI HUYEN",
          identity = "040191014068",
          mobile = "0123456789"
      };
      
      var timestamp = DateTime.Now.ToString("yyyyMMddHHmmssfff");
      var secretKey = "YOUR_SECRET_KEY";
      var bodyJson = JsonSerializer.Serialize(body);
      var message = $"{timestamp}:{bodyJson}";
      var signature = CreateHmacSha512(secretKey, message);

      var request = new HttpRequestMessage(HttpMethod.Post, "https://open-api.tingee.vn/v1/create-va");
      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

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 CreateVA {
public static void main(String[] args) throws Exception {
  String bodyJson = "{\"isNotifyAccountNumber\":false,\"accountType\":\"personal-account\",\"bankBin\":\"970418\",\"accountNumber\":\"0935926988\",\"accountName\":\"NGUYEN THI HUYEN\",\"identity\":\"040191014068\",\"mobile\":\"0123456789\"}";
  String secretKey = "YOUR_SECRET_KEY";
  String timestamp = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMddHHmmssSSS"));

  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/create-va"))
      .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

function createVA() {
  $body = [
      "isNotifyAccountNumber" => false,
      "accountType" => "personal-account",
      "bankBin" => "970418",
      "accountNumber" => "0935926988",
      "accountName" => "NGUYEN THI HUYEN",
      "identity" => "040191014068",
      "mobile" => "0123456789"
  ];

  $jsonBody = json_encode($body);
  $timestamp = date("YmdHis") . substr((string)microtime(true), -3);
  $secretKey = "YOUR_SECRET_KEY";

  $message = $timestamp . ":" . $jsonBody;
  $signature = hash_hmac("sha512", $message, $secretKey);

  $ch = curl_init();
  curl_setopt_array($ch, [
      CURLOPT_URL => "https://open-api.tingee.vn/v1/create-va",
      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);
  $err = curl_error($ch);
  curl_close($ch);

  if ($err) {
      echo "cURL Error: " . $err;
  } else {
      echo $response;
  }
}

Response mẫu

{
  "code": "00",
  "message": "Success",
  "data": {
    "confirmId": "VA_CONFIRM_123456",
    "shopId": 109876,
    "authorizeLink": "https://tpb.vn/authorize/..."
  }
}

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.confirmId	string	Mã xác nhận cần dùng cho API confirm-va.
data.shopId	string	ID cửa hàng (trả về khi hệ thống tạo mới hoặc gán vào cửa hàng hiện tại).
data.authorizeLink	string	Link đăng nhập web TPBank BIZ (trả về trong trường hợp liên kết tài khoản ngân hàng TPBank).

---

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.