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
Base URL
Section titled “Base URL”https://<host>/voting/api| Environment | Host |
|---|---|
| Staging | provided to you separately |
| Production | provided 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.
Credentials
Section titled “Credentials”Each partner is issued a credential pair, delivered out-of-band (never in code or plaintext email):
| Field | Example | Notes |
|---|---|---|
apiKeyId | pk_xxxxxxxxxxxxxxxxxxxxxxxx | Public id, sent in the X-Api-Key header. |
secret | 43ee…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.
Authentication
Section titled “Authentication”Every request carries three headers:
| Header | Value |
|---|---|
X-Api-Key | Your apiKeyId. |
X-Timestamp | Current time in Unix epoch milliseconds (e.g. 1782779064000). |
X-Signature | hex( HMAC_SHA256( secret, "{X-Timestamp}.{queryString}" ) ). |
What you sign
Section titled “What you sign”The signed message is:
{X-Timestamp}.{queryString}{X-Timestamp}— the same value you send in theX-Timestampheader.{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.
Timestamp window
Section titled “Timestamp window”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.
Request
Section titled “Request”| Param | Required | Type | Default | Description |
|---|---|---|---|---|
tenantId | yes | string | — | Tenant to read. Must be in your allowed tenants. |
orderId | no | string | — | Filter by exact order id. |
email | no | string | — | Filter by the voter’s email. |
from | no | string | — | ISO-8601 datetime. Include rows with paymentTime >= from. |
to | no | string | — | ISO-8601 datetime. Include rows with paymentTime <= to. |
page | no | number | 1 | 1-based page index. |
limit | no | number | 10 | Page size. Max 100 (larger values are clamped to 100). |
Only transactions with paymentStatus = SUCCESS are returned, newest first.
Example
Section titled “Example”# 1) Build the EXACT query string you will sendQS="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}"Response — 200 OK
Section titled “Response — 200 OK”{ "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 }}transactions[]
Section titled “transactions[]”| Field | Type | Description |
|---|---|---|
eventName | string | null | Event name. |
productName | string | null | Candidate/product name. |
pointPackage | number | null | Points in the purchased package. |
promotion | string | null | Promotion applied (e.g. "n/a", "x2"). |
totalPointAdded | number | null | Points added by this transaction (totalPoint − currentPoint). |
currentPoint | number | null | Candidate point total before this transaction. |
totalPoint | number | null | Candidate point total after this transaction. |
registrationNumber | string | null | Candidate registration number (SBD). |
orderId | string | Order id. |
productId | string | Candidate/product id. |
createdAt | string | null | Order created time (ISO-8601). |
completedAt | string | null | Payment completed time (ISO-8601). |
amount | number | Charged amount. |
paymentStatus | string | Always SUCCESS. |
userId | string | null | Voter email. |
pagination
Section titled “pagination”| Field | Type | Description |
|---|---|---|
total | number | Total matching rows across all pages. |
page | number | Current page (echoes the request). |
limit | number | Page size (echoes the request, after clamping). |
totalPages | number | ceil(total / limit). |
hasMore | boolean | true if more pages follow. |
Errors
Section titled “Errors”Authentication / authorization
Section titled “Authentication / authorization”Returned with a real HTTP status and a stable string code:
{ "code": "INVALID_SIGNATURE", "message": "Chữ ký không hợp lệ" }| HTTP | code | Cause |
|---|---|---|
| 401 | INVALID_SIGNATURE | Missing/invalid signature, or unknown X-Api-Key. |
| 401 | TIMESTAMP_OUT_OF_RANGE | X-Timestamp not within ±5 minutes of server time. |
| 403 | PARTNER_SUSPENDED | Your partner account is suspended. |
| 403 | TENANT_NOT_ALLOWED | The requested tenantId is not in your allowed tenants. |
Validation
Section titled “Validation”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" } ] }}Reference implementations
Section titled “Reference implementations”Node.js
Section titled “Node.js”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);Python
Section titled “Python”import hashlib, hmac, timefrom urllib.parse import urlencodeimport 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}))Checklist
Section titled “Checklist”- Build the query string yourself; sign that exact string; send it verbatim.
-
X-Timestampis epoch milliseconds, regenerated per request (±5 min window). -
X-Signatureis lowercase hex of HMAC-SHA256 over"{timestamp}.{queryString}". -
tenantIdis one of your allowed tenants. - Treat
4xx(code) and200with a non-zeroerrorCodeboth as failures.
The EP wallet users endpoint uses the same credentials, headers, and signing rules.