Skip to content

Partner API — EP wallet users

List the users that already have an EP wallet in a tenant, enriched with their platform profile. This is a read-only Partner API, authenticated with a per-request HMAC-SHA256 signature — no JWT, no cookies.

GET /voting/api/v1/partner/ep/wallet-users

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

The full URL is https://<host>/voting/api/v1/partner/ep/wallet-users.

Every request carries three headers:

HeaderValue
X-Api-KeyYour apiKeyId.
X-TimestampCurrent time in Unix epoch milliseconds, within ±5 minutes of server time.
X-Signaturehex( HMAC_SHA256( secret, "{X-Timestamp}.{queryString}" ) ).

{queryString} is the exact query string you send (everything after ?, already URL-encoded, in the same order). The signature binds every query parameter, so build the query string yourself, sign that exact string, and send it verbatim. You may only query tenants in your allowed tenants list.

Pagination is cursor-based (the underlying store has no stable offset).

ParamRequiredTypeDefaultDescription
tenantIdyesstring—Tenant to read. Must be in your allowed tenants.
emailnostring—Look up a single holder by email (exact; case-insensitive). Returns 0 or 1 user.
limitnonumber20Page size. Max 100 (larger values are clamped to 100).
cursornostring—Opaque cursor from a previous response’s nextCursor. Omit for the first page.
Terminal window
# 1) Build the EXACT query string you will send
QS="tenantId=7g1RP3&limit=20"
# 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/ep/wallet-users?${QS}" \
-H "X-Api-Key: <your-api-key-id>" \
-H "X-Timestamp: ${TS}" \
-H "X-Signature: ${SIG}"
{
"tenantId": "7g1RP3",
"users": [
{
"email": "alice@example.com",
"balance": 259,
"walletStatus": "ACTIVE",
"walletCreatedAt": "2026-06-20T03:45:26.904Z",
"hasAccount": true,
"name": "Alice Nguyen",
"phone": "+84837337383",
"phoneVerified": false
}
],
"count": 1,
"nextCursor": "eyJ0ZW5hbnRJZCI6IjdnMVJQMyIsIndhbGxldElkIjoiVVNFUiM3ZzFSUDMjYm9iQGV4YW1wbGUuY29tIn0="
}
FieldTypeDescription
emailstringWallet holder email (normalized).
balancenumberCurrent EP balance.
walletStatusstringWallet status — ACTIVE or FROZEN.
walletCreatedAtstring | nullWhen the wallet was first created (ISO-8601).
hasAccountbooleantrue if a platform account exists for this email.
namestring | nullDisplay name. null when no account.
phonestring | nullPhone number. null when none.
phoneVerifiedbooleanWhether the phone is verified. Defaults to false.
FieldTypeDescription
tenantIdstringEchoes the request.
countnumberNumber of users in this page.
nextCursorstring | nullOpaque cursor for the next page; null on the last page.

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) return HTTP 200 with a non-zero errorCode:

{
"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 listWalletUsers(params) {
const queryString = new URLSearchParams(params).toString(); // exact string to sign + send
const timestamp = Date.now().toString();
const signature = crypto
.createHmac("sha256", SECRET)
.update(`${timestamp}.${queryString}`)
.digest("hex");
const res = await fetch(
`${BASE_URL}/v1/partner/ep/wallet-users?${queryString}`,
{
headers: {
"X-Api-Key": API_KEY_ID,
"X-Timestamp": timestamp,
"X-Signature": signature,
},
},
);
return res.json();
}
// Page through every wallet holder in a tenant.
async function listAll(tenantId) {
const all = [];
let cursor;
do {
const params = { tenantId, limit: "100", ...(cursor ? { cursor } : {}) };
const page = await listWalletUsers(params);
all.push(...page.users);
cursor = page.nextCursor;
} while (cursor);
return all;
}
listAll("7g1RP3").then((users) => console.log(users.length, "wallet users"));
  • 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.
  • Page until nextCursor is null (do not stop on a short page).
  • Treat 4xx (code) and 200 with a non-zero errorCode both as failures.