Unlink an account

Use this API to unlink an account from the Direct Debit service.

If the customer's account requires verification before unlinking, Tingee returns a link to a web page where the customer enters an OTP.

DELETE

URLhttps://open-api.tingee.vn/v1/direct-debit/delete-subscription

Create a request to unlink a bank account. The unlinking either completes immediately or returns an OTP verification URL.

Header Request

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

Body Parameter

Field	Type	Required	Description
requestId	string	✓	ID of the request to Tingee (UUID).
subscriptionId	string	✓	ID of the linked bank account (UUID). The account must be active.
tokenRef	string	✓	Reference code of the customer's account.
returnUrl	string	✓	URL to redirect back to the partner after completion.

Code samples

cURL

curl --location --request DELETE 'https://open-api.tingee.vn/v1/direct-debit/delete-subscription' \
--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 '{
  "requestId": "550760e0-1cc2-44b9-85ba-eb318e228b4f",
  "subscriptionId": "89188e53-eba3-40fa-9323-04422ced3637",
  "tokenRef": "TKN-12345678",
  "returnUrl": "https://example.com"
}'

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 directDebitDeleteSubscription() {
    const body = {
        requestId: "550760e0-1cc2-44b9-85ba-eb318e228b4f",
        subscriptionId: "89188e53-eba3-40fa-9323-04422ced3637",
        tokenRef: "TKN-12345678",
        returnUrl: "https://example.com",
    };

    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-debit/delete-subscription",
        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);
}

directDebitDeleteSubscription();

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
        {
            requestId = "550760e0-1cc2-44b9-85ba-eb318e228b4f",
            subscriptionId = "89188e53-eba3-40fa-9323-04422ced3637",
            tokenRef = "TKN-12345678",
            returnUrl = "https://example.com"
        };

        // 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.Delete, "https://open-api.tingee.vn/v1/direct-debit/delete-subscription");
        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 = "{\"requestId\":\"550760e0-1cc2-44b9-85ba-eb318e228b4f\",\"subscriptionId\":\"89188e53-eba3-40fa-9323-04422ced3637\",\"tokenRef\":\"TKN-12345678\",\"returnUrl\":\"https://example.com\"}";

        // 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-debit/delete-subscription"))
                .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 = [
    "requestId" => "550760e0-1cc2-44b9-85ba-eb318e228b4f",
    "subscriptionId" => "89188e53-eba3-40fa-9323-04422ced3637",
    "tokenRef" => "TKN-12345678",
    "returnUrl" => "https://example.com",
];

// 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-debit/delete-subscription",
    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);

Sample Response

When the unlinking completes immediately:

{
  "code": "00",
  "message": "Success",
  "data": {
    "code": "00"
  }
}

When the customer must verify with an OTP:

{
  "code": "00",
  "message": "Success",
  "data": {
    "code": "01",
    "confirmUrl": "https://direct-debit.tingee.vn/confirm-delete-subscription?requestId=550760e0-1cc2-44b9-85ba-eb318e228b4f&clientId=...&subscriptionId=89188e53-eba3-40fa-9323-04422ced3637&signature=...&expirationTime=20260115124049"
  }
}

Field	Type	Description
code	string	Response code (00 means success).
message	string	Detailed message.
data.code	string	Unlinking result: - 00: The account was unlinked successfully. - 01: The customer must verify with an OTP via confirmUrl.
data.confirmUrl	string	URL of the OTP verification page to redirect the customer to (only present when data.code = 01). The URL is valid for 30 minutes.

---

Common error codes

Code	Description	How to handle
1067	No active subscription to unlink was found	Check subscriptionId and tokenRef; the subscription may have been unlinked already — use Query account status to confirm.
1068, 1009	Direct Debit is not configured for the Merchant, or the payment platform is not supported	Contact TINGEE to check the Merchant's Direct Debit configuration.
90, 91, 92, 97	Request authentication error (timestamp, client-id, signature)	See System error codes.
Others	Other errors	See Error codes.