Approve payment order

POST

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

Approve a disbursement payment order (Checker)

Header Request

Header	Required	Description
Content-Type	✓	application/json
x-client-id	✓	Partner identifier issued by TINGEE.
x-signature	✓	HMAC SHA512 authentication signature.
x-request-timestamp	✓	Time the request is sent (format: yyyyMMddHHmmssSSS, UTC+7)

Body Parameter

Field	Type	Required	Description
bankBin	string	✓	Bank BIN. Currently only 970418 (BIDV) is supported. The API uses the BIDV authorization session of the Checker role.
actionType	string	✓	Disbursement order type - INTERNAL_TRANSFER: Domestic transfer - SALARY: Salary payment - BILL_PAYMENT: Bill / statement payment
transactionIds	array	✓	List of pending transaction IDs to approve (the id field in the Transaction inquiry result with inquiryType = PENDING_APPROVAL_LIST).

Code samples

cURL

curl --location --request POST 'https://open-api.tingee.vn/v1/direct-link/approve-transfer' \
--header 'accept: application/json' \
--header 'x-client-id: YOUR_CLIENT_ID' \
--header 'x-request-timestamp: 20240509154004003' \
--header 'x-signature: YOUR_SIGNATURE' \
--header 'Content-Type: application/json' \
--data '{
  "bankBin": "970418",
  "actionType": "INTERNAL_TRANSFER",
  "transactionIds": [
    "PM0226061000074420"
  ]
}'

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 directLinkApproveTransfer() {
    const body = {
        bankBin: "970418",
        actionType: "INTERNAL_TRANSFER",
        transactionIds: [
            "PM0226061000074420",
        ],
    };

    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: "POST",
        url: "https://open-api.tingee.vn/v1/direct-link/approve-transfer",
        data: bodyJson,
        headers: {
            accept: "application/json",
            "Content-Type": "application/json",
            "x-client-id": CLIENT_ID,
            "x-request-timestamp": timestamp,
            "x-signature": signature,
        },
    });

    console.log(res.data);
}

directLinkApproveTransfer();

C#

using System;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Encodings.Web;
using System.Text.Json;
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 body = new
        {
            bankBin = "970418",
            actionType = "INTERNAL_TRANSFER",
            transactionIds = new object[]
            {
                "PM0226061000074420"
            }
        };

        // Do not escape non-ASCII / special characters so the JSON matches TINGEE's JSON.stringify
        var jsonOptions = new JsonSerializerOptions { Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping };
        var bodyJson = JsonSerializer.Serialize(body, jsonOptions);

        // 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.Post, "https://open-api.tingee.vn/v1/direct-link/approve-transfer");
        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);
        request.Content = new StringContent(bodyJson, Encoding.UTF8, "application/json");

        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()
        String bodyJson = "{\"bankBin\":\"970418\",\"actionType\":\"INTERNAL_TRANSFER\",\"transactionIds\":[\"PM0226061000074420\"]}";

        // 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-link/approve-transfer"))
                .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("POST", HttpRequest.BodyPublishers.ofString(bodyJson, StandardCharsets.UTF_8))
                .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";

$body = [
    "bankBin" => "970418",
    "actionType" => "INTERNAL_TRANSFER",
    "transactionIds" => [
        "PM0226061000074420",
    ],
];

// Do not escape "/" or non-ASCII characters so the JSON matches TINGEE's JSON.stringify
$bodyJson = json_encode($body, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);

// 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-link/approve-transfer",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => $bodyJson,
    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": {
    "successfulTransactions": [],
    "failedTransactions": [],
    "requireAuth": true,
    "transAuth": {
      "authType": "SMARTOTP",
      "expTime": 120,
      "qrData": "OTkwMDVCMDUwMDMyMTc4MTE0MjI4NDkwNS1kYjdjZWU3NC1hNTdjLTQxMjItODljZi1jZmEyYWNjMDkyZjgwNjAwMDQ3OTczMjAwMDEzQklEVklCQU5LX1RSQU5TX09UUA=="
    },
    "confirmId": "TXNKEY_APPROVAL_25607354makerotv_a8993883-d5fe-4ced-a0c0-20cff5b5120b",
    "confirmUrl": null
  }
}

Field	Type	Description
code	string	Result code (00 = Success).
message	string	Response message.
data	object	Object containing the transaction approval result.
data.successfulTransactions	array	Transactions approved successfully (raw result from BIDV; each item has a transactionId). Usually empty when requireAuth = true — the final result is returned at the OTP confirmation step.
data.failedTransactions	array	Transactions whose approval failed.
data.requireAuth	boolean	Whether additional authentication is required (e.g. SmartOTP).
data.transAuth	object	Additional authentication details (only set when requireAuth = true, otherwise null).
data.confirmId	string	Confirmation key. When requireAuth = true, pass this value together with the OTP to the Confirm disbursement approval API to complete the approval.
data.confirmUrl	string	URL where the user confirms the transaction (if BIDV returns it).
data.transaction	object	Summary of the approved batch order (only for SALARY / BILL_PAYMENT), including: id (transaction ID), originId, status, amount, currency, feeTotal, feeMethod, processDate, effectiveDate.

data.transAuth details (when requireAuth = true)

Field	Type	Description
authType	string	Authentication method (e.g. SMARTOTP).
expTime	number	Validity period of the QR code (in seconds).
qrData	string	Data string used to render the QR code image; scan it with the BIDV Direct app to get the SmartOTP.

---

Common error codes

Code	Description	How to handle
1077	The BIDV authorization session of the approver (Checker) has expired or has not been granted	Call Get authorization URL with role = Checker to re-authorize, then resend the approval request.
1021	The bank is not supported for this API	Check bankBin; this API only supports BIDV (970418).
90, 91, 92, 97	Request authentication error (timestamp, client-id, signature)	See System error codes.
Others	Other errors	See Error codes.