POS order details

Use this API to look up the information and payment status of a POS order you created. The data is fetched directly from the Payoo system.

GET

URLhttps://open-api.tingee.vn/v1/get-detail-pos-bill

Look up POS order details by billId.

Header Request

Header	Required	Description
x-client-id	✓	Partner identifier issued by TINGEE.
x-signature	✓	HMAC SHA512 authentication signature. For GET requests, the string to sign is {x-request-timestamp}:{}. See How to generate the signature.
x-request-timestamp	✓	Time the request is sent (format: yyyyMMddHHmmssSSS, UTC+7)

Query Parameters

Field	Type	Required	Description
bankBin	string	✓	Always pass PAYOO.
vaAccountNumber	string	✓	Payoo POS device code.
billId	string	✓	Order ID received from the Create a POS order API.

Code samples

cURL

curl --location --request GET 'https://open-api.tingee.vn/v1/get-detail-pos-bill?bankBin=PAYOO&vaAccountNumber=POS00012345&billId=9f1c2b7e4a5d4c3b8e2f1a0b9c8d7e6f' \
--header 'accept: application/json' \
--header 'x-client-id: YOUR_CLIENT_ID' \
--header 'x-request-timestamp: 20240509154004003' \
--header 'x-signature: YOUR_SIGNATURE'

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 getDetailPosBill() {
    const body = {}; // Request has no body: sign the string "{}"

    const params = {
        bankBin: "PAYOO",
        vaAccountNumber: "POS00012345",
        billId: "9f1c2b7e4a5d4c3b8e2f1a0b9c8d7e6f",
    };

    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: "GET",
        url: "https://open-api.tingee.vn/v1/get-detail-pos-bill",
        params,
        headers: {
            accept: "application/json",
            "Content-Type": "application/json",
            "x-client-id": CLIENT_ID,
            "x-request-timestamp": timestamp,
            "x-signature": signature,
        },
    });

    console.log(res.data);
}

getDetailPosBill();

C#

using System;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
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 bodyJson = "{}"; // Request has no body: sign the string "{}"

        // 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.Get, "https://open-api.tingee.vn/v1/get-detail-pos-bill?bankBin=PAYOO&vaAccountNumber=POS00012345&billId=9f1c2b7e4a5d4c3b8e2f1a0b9c8d7e6f");
        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);

        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(). Request has no body: sign the string "{}"
        String bodyJson = "{}";

        // 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/get-detail-pos-bill?bankBin=PAYOO&vaAccountNumber=POS00012345&billId=9f1c2b7e4a5d4c3b8e2f1a0b9c8d7e6f"))
                .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("GET", HttpRequest.BodyPublishers.noBody())
                .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";

$bodyJson = "{}"; // Request has no body: sign the string "{}"

// 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/get-detail-pos-bill?bankBin=PAYOO&vaAccountNumber=POS00012345&billId=9f1c2b7e4a5d4c3b8e2f1a0b9c8d7e6f",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    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": {
    "orderId": "9f1c2b7e4a5d4c3b8e2f1a0b9c8d7e6f",
    "amount": 150000,
    "expirationTime": "20261014153000",
    "createTime": "20261014150000",
    "status": 1,
    "transactionCode": "PY123456789"
  }
}

Field	Type	Description
code	string	Result code (00 = Success).
message	string	Response message.
data.orderId	string	Order ID (the same as billId).
data.amount	number	Order amount.
data.expirationTime	string	Order expiration time.
data.createTime	string	Order creation time.
data.status	number	Order status according to Payoo's conventions.
data.transactionCode	string	Payoo payment transaction code (once the order has been paid).

---

Common error codes

Code	Description	How to handle
1010	The Merchant's account number was not found	Check the vaAccountNumber and bankBin of the linked POS terminal.
1063	Not supported for this bank	The API only applies to bankBin = "PAYOO".
400	Error from Payoo or invalid data	message contains the detailed error (e.g. billId does not exist at Payoo).
90, 91, 92, 97	Request authentication error (timestamp, client-id, signature)	See System error codes.
Others	Other errors	See Error codes.