Từ chối lệnh chi hộ

DELETE

URLhttps://open-api.tingee.vn/v1/direct-link/reject-transaction

Từ chối phê duyệt lệnh chi hộ (Checker)

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. Hiện chỉ hỗ trợ 970418 (BIDV). API sử dụng phiên ủy quyền BIDV của vai trò Checker.
actionType	string	✓	Loại lệnh chi hộ - INTERNAL_TRANSFER: Chuyển tiền trong nước - SALARY: Thanh toán Lương - BILL_PAYMENT: Thanh toán Hóa đơn-Bảng kê
transactionIds	array	✓	Danh sách mã giao dịch đang chờ duyệt cần từ chối (trường id trong kết quả Truy vấn giao dịch với inquiryType = PENDING_APPROVAL_LIST).
rejectReason	string	✕	Lý do từ chối (nếu có).

Ví dụ mã nguồn

cURL

curl --location --request DELETE 'https://open-api.tingee.vn/v1/direct-link/reject-transaction' \
--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"
  ],
  "rejectReason": "Thông tin không chính xác"
}'

NestJS

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 directLinkRejectTransaction() {
    const body = {
        bankBin: "970418",
        actionType: "INTERNAL_TRANSFER",
        transactionIds: [
            "PM0226061000074420",
        ],
        rejectReason: "Thông tin không chính xác",
    };

    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: "DELETE",
        url: "https://open-api.tingee.vn/v1/direct-link/reject-transaction",
        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);
}

directLinkRejectTransaction();

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"
            },
            rejectReason = "Thông tin không chính xác"
        };

        // Không escape tiếng Việt / ký tự đặc biệt để khớp với JSON.stringify phía TINGEE
        var jsonOptions = new JsonSerializerOptions { Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping };
        var bodyJson = JsonSerializer.Serialize(body, jsonOptions);

        // 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.Delete, "https://open-api.tingee.vn/v1/direct-link/reject-transaction");
        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 {
        // JSON minified, giống kết quả JSON.stringify()
        String bodyJson = "{\"bankBin\":\"970418\",\"actionType\":\"INTERNAL_TRANSFER\",\"transactionIds\":[\"PM0226061000074420\"],\"rejectReason\":\"Thông tin không chính xác\"}";

        // 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/reject-transaction"))
                .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("DELETE", 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",
    ],
    "rejectReason" => "Thông tin không chính xác",
];

// Không escape "/" và tiếng Việt để khớp với JSON.stringify phía TINGEE
$bodyJson = json_encode($body, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);

// 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/reject-transaction",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "DELETE",
    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);

Response mẫu

{
  "code": "00",
  "message": "Success",
  "data": {
    "successfulTransactions": [
      {
        "transactionId": "PM0226061000074420",
        "transactionType": "in-bank",
        "amount": 32987,
        "currency": "VND",
        "feeAccountNumber": "8600007007",
        "transactionCode": "PM02",
        "effectiveDate": "2026-06-10",
        "amountText": "Ba mươi hai nghìn chín trăm tám mươi bảy đồng",
        "feeTotal": 11000,
        "feeMethod": "O",
        "remark": "Chuyen tien",
        "originId": "TRANS_1006_A04",
        "priority": true,
        "status": "REJECTED",
        "creditAccountType": "ACCOUNT",
        "creditAccountNumber": "2220366666",
        "creditAccountName": "NGUYEN VAN A",
        "creditBankCode": "01202001",
        "creditBankShortName": "BIDV",
        "debitAccountNumber": "8600007007",
        "debitAccountName": "Title 1 8600007007"
      }
    ],
    "failedTransactions": []
  }
}

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	Đối tượng chứa kết quả từ chối giao dịch.
data.successfulTransactions	array	Danh sách thông tin các giao dịch đã từ chối thành công. Với INTERNAL_TRANSFER, mảng chứa thông tin chi tiết một giao dịch đại diện (giao dịch đầu tiên được từ chối) — dùng Truy vấn giao dịch để kiểm tra trạng thái từng giao dịch khi từ chối nhiều giao dịch cùng lúc.
data.failedTransactions	array	Danh sách thông tin các giao dịch từ chối thất bại.

Chi tiết phần tử trong successfulTransactions / failedTransactions

Trường	Kiểu	Mô tả
transactionId	string	Mã giao dịch phía BIDV.
transactionType	string	Loại giao dịch: in-bank (nội bộ BIDV), regular-out (chuyển thường liên ngân hàng), fast-out (chuyển nhanh NAPAS 247).
transactionCode	string	Mã loại giao dịch phía BIDV (VD: PM02, PM13).
status	string	Trạng thái giao dịch do BIDV trả về (VD: INIT, PENDING_APPROVAL, PROCESSING, BANK_PROCESSING, APPROVED, SUCCESS, REJECTED, FAILED).
amount	number	Số tiền giao dịch.
amountText	string	Số tiền bằng chữ.
currency	string	Loại tiền tệ (VND).
remark	string	Nội dung giao dịch.
approvalNote	string	Ghi chú đẩy duyệt của người lập lệnh (Maker).
originId	string	Mã tham chiếu requestId do đối tác gửi lên khi tạo lệnh.
priority	boolean	Cờ ưu tiên xử lý.
effectiveDate	string	Ngày hiệu lực của giao dịch.
acceptedDate	string	Thời điểm ngân hàng tiếp nhận giao dịch.
approvedDate	string	Thời điểm giao dịch được phê duyệt.
processDate	string	Thời điểm ngân hàng xử lý giao dịch.
feeMethod	string	Bên chịu phí: O (tài khoản thanh toán chịu phí), B (người nhận chịu phí).
feeAccountNumber	string	Tài khoản thu phí.
feeAmount	number	Phí giao dịch (chưa gồm VAT).
feeVAT	number	Thuế VAT của phí.
feeTotal	number	Tổng phí giao dịch.
debitAccountNumber	string	Số tài khoản trích nợ.
debitAccountName	string	Tên tài khoản trích nợ.
creditAccountType	string	Hình thức nhận tiền: ACCOUNT (số tài khoản) hoặc ID (giấy tờ tùy thân).
creditAccountNumber	string	Số tài khoản người nhận.
creditAccountName	string	Tên người nhận.
creditBankCode	string	Mã ngân hàng nhận theo chuẩn CITAD (VD: 01202001 là BIDV).
creditBankName	string	Tên ngân hàng nhận.
creditBankShortName	string	Tên viết tắt ngân hàng nhận.
creditBankAbbr	string	Tên rút gọn ngân hàng nhận.
creditBranchCode	string	Mã chi nhánh ngân hàng nhận.
creditBranchName	string	Tên chi nhánh ngân hàng nhận.
creditId	string	Số giấy tờ tùy thân người nhận (khi creditAccountType = ID).
creditIssueDate	string	Ngày cấp giấy tờ tùy thân.
creditIssueAddress	string	Nơi cấp giấy tờ tùy thân.
creditCurrency	string	Loại tiền tệ của người nhận.
originalCreditAccountNumber	string	Số tài khoản người nhận ban đầu (theo dữ liệu gốc khi lập lệnh, nếu BIDV trả về).
originalCreditName	string	Tên người nhận ban đầu (theo dữ liệu gốc khi lập lệnh, nếu BIDV trả về).

Trường nào BIDV không trả về sẽ không xuất hiện trong phần tử (hoặc có giá trị null).

---

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

Code	Mô tả	Hướng xử lý
1077	Phiên ủy quyền BIDV của người duyệt (Checker) đã hết hạn hoặc chưa được cấp	Gọi Lấy đường dẫn xác thực với role = Checker để ủy quyền lại, sau đó từ chối lại.
1021	Ngân hàng không được hỗ trợ cho API này	Kiểm tra bankBin; API này chỉ hỗ trợ BIDV (970418).
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.