Skip to content

Partner API — Vote transactions

Read vote transactions for one tenant. This is a read-only Partner API, authenticated with a per-request HMAC-SHA256 signature — no JWT, no cookies.

GET /voting/api/v1/partner/voting/transactions

https://<host>/voting/api
EnvironmentHost
Stagingprovided to you separately
Productionprovided to you separately

All paths below are relative to the base URL, so the full URL is https://<host>/voting/api/v1/partner/voting/transactions.

Each partner is issued a credential pair, delivered out-of-band (never in code or plaintext email):

FieldExampleNotes
apiKeyIdpk_xxxxxxxxxxxxxxxxxxxxxxxxPublic id, sent in the X-Api-Key header.
secret43ee…a30f61 (64 hex chars)Secret HMAC key — never expose it.

Your account is also configured with a list of allowed tenants. You may only query tenants in that list.

Every request carries three headers:

HeaderValue
X-Api-KeyYour apiKeyId.
X-TimestampCurrent time in Unix epoch milliseconds (e.g. 1782779064000).
X-Signaturehex( HMAC_SHA256( secret, "{X-Timestamp}.{queryString}" ) ).

The signed message is:

{X-Timestamp}.{queryString}
  • {X-Timestamp} — the same value you send in the X-Timestamp header.
  • {queryString} — the exact query string you send, i.e. everything after the ?, already URL-encoded, in the same order you send it. For example: tenantId=7g1RP3&page=1&limit=10.

The signature binds every query parameter, so changing, adding, removing, or reordering any parameter (or the timestamp) after signing invalidates the request. X-Signature is the lowercase hex of the HMAC-SHA256 digest.

X-Timestamp must be within ±5 minutes of the server clock. Generate a fresh timestamp and signature for every request — signatures are short-lived, which, together with the endpoint being read-only, blocks replay.

ParamRequiredTypeDefaultDescription
tenantIdyesstring—Tenant to read. Must be in your allowed tenants.
orderIdnostring—Filter by exact order id.
emailnostring—Filter by the voter’s email.
fromnostring—ISO-8601 datetime. Include rows with paymentTime >= from.
tonostring—ISO-8601 datetime. Include rows with paymentTime <= to.
pagenonumber11-based page index.
limitnonumber10Page size. Max 100 (larger values are clamped to 100).

Only transactions with paymentStatus = SUCCESS are returned, newest first.

Terminal window
# 1) Build the EXACT query string you will send
QS="tenantId=7g1RP3&page=1&limit=10"
# 2) Fresh timestamp (epoch ms) + signature over "${TS}.${QS}"
SECRET="<your-secret>"
TS=$(($(date +%s)*1000))
SIG=$(printf "%s.%s" "$TS" "$QS" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')
# 3) Send it — pass ?$QS verbatim (do NOT use -G/--data-urlencode)
curl "https://<host>/voting/api/v1/partner/voting/transactions?${QS}" \
-H "X-Api-Key: <your-api-key-id>" \
-H "X-Timestamp: ${TS}" \
-H "X-Signature: ${SIG}"
{
"transactions": [
{
"eventName": "Video duoc yeu thich nhat",
"productName": "Nguyen Thi Thuy Trang",
"pointPackage": 3,
"promotion": "n/a",
"totalPointAdded": 3,
"currentPoint": 400,
"totalPoint": 403,
"registrationNumber": "070",
"orderId": "KJGCnLJsdc92",
"productId": "qBZL",
"createdAt": "2026-06-29T17:37:59.954Z",
"completedAt": "2026-06-29T17:37:59.954Z",
"amount": 0,
"paymentStatus": "SUCCESS",
"userId": "hahn4048@gmail.com"
}
],
"pagination": { "total": 1, "page": 1, "limit": 10, "totalPages": 1, "hasMore": false }
}
FieldTypeDescription
eventNamestring | nullEvent name.
productNamestring | nullCandidate/product name.
pointPackagenumber | nullPoints in the purchased package.
promotionstring | nullPromotion applied (e.g. "n/a", "x2").
totalPointAddednumber | nullPoints added by this transaction (totalPoint − currentPoint).
currentPointnumber | nullCandidate point total before this transaction.
totalPointnumber | nullCandidate point total after this transaction.
registrationNumberstring | nullCandidate registration number (SBD).
orderIdstringOrder id.
productIdstringCandidate/product id.
createdAtstring | nullOrder created time (ISO-8601).
completedAtstring | nullPayment completed time (ISO-8601).
amountnumberCharged amount.
paymentStatusstringAlways SUCCESS.
userIdstring | nullVoter email.
FieldTypeDescription
totalnumberTotal matching rows across all pages.
pagenumberCurrent page (echoes the request).
limitnumberPage size (echoes the request, after clamping).
totalPagesnumberceil(total / limit).
hasMorebooleantrue if more pages follow.

Returned with a real HTTP status and a stable string code:

{ "code": "INVALID_SIGNATURE", "message": "Chữ ký không hợp lệ" }
HTTPcodeCause
401INVALID_SIGNATUREMissing/invalid signature, or unknown X-Api-Key.
401TIMESTAMP_OUT_OF_RANGEX-Timestamp not within ±5 minutes of server time.
403PARTNER_SUSPENDEDYour partner account is suspended.
403TENANT_NOT_ALLOWEDThe requested tenantId is not in your allowed tenants.

Invalid/missing query parameters (e.g. missing tenantId, malformed from/to) return HTTP 200 with a non-zero errorCode — this differs from the auth errors above:

{
"errorCode": 100400,
"message": "Dữ liệu không hợp lệ",
"data": { "params": [ { "path": "tenantId", "message": "tenantId bắt buộc" } ] }
}
const crypto = require("crypto");
const BASE_URL = "https://<host>/voting/api";
const API_KEY_ID = "<your-api-key-id>";
const SECRET = "<your-secret>";
async function listVoteTransactions(params) {
// Build the exact query string, then sign it (order matters).
const queryString = new URLSearchParams(params).toString();
const timestamp = Date.now().toString();
const signature = crypto
.createHmac("sha256", SECRET)
.update(`${timestamp}.${queryString}`)
.digest("hex");
const res = await fetch(
`${BASE_URL}/v1/partner/voting/transactions?${queryString}`,
{
headers: {
"X-Api-Key": API_KEY_ID,
"X-Timestamp": timestamp,
"X-Signature": signature,
},
},
);
return res.json();
}
listVoteTransactions({ tenantId: "7g1RP3", page: "1", limit: "10" }).then(console.log);
import hashlib, hmac, time
from urllib.parse import urlencode
import requests
BASE_URL = "https://<host>/voting/api"
API_KEY_ID = "<your-api-key-id>"
SECRET = "<your-secret>"
def list_vote_transactions(params: dict):
query_string = urlencode(params) # exact string to sign + send
timestamp = str(int(time.time() * 1000))
signature = hmac.new(
SECRET.encode(), f"{timestamp}.{query_string}".encode(), hashlib.sha256
).hexdigest()
# Append the pre-built query string to the URL (do NOT pass params= here).
url = f"{BASE_URL}/v1/partner/voting/transactions?{query_string}"
return requests.get(
url,
headers={
"X-Api-Key": API_KEY_ID,
"X-Timestamp": timestamp,
"X-Signature": signature,
},
).json()
print(list_vote_transactions({"tenantId": "7g1RP3", "page": 1, "limit": 10}))
  • Build the query string yourself; sign that exact string; send it verbatim.
  • X-Timestamp is epoch milliseconds, regenerated per request (±5 min window).
  • X-Signature is lowercase hex of HMAC-SHA256 over "{timestamp}.{queryString}".
  • tenantId is one of your allowed tenants.
  • Treat 4xx (code) and 200 with a non-zero errorCode both as failures.

The EP wallet users endpoint uses the same credentials, headers, and signing rules.