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
Base URL
Section titled “Base URL”https://<host>/voting/api| Environment | Host |
|---|---|
| Staging | provided to you separately |
| Production | provided to you separately |
The full URL is https://<host>/voting/api/v1/partner/ep/wallet-users.
Authentication (summary)
Section titled “Authentication (summary)”Every request carries three headers:
| Header | Value |
|---|---|
X-Api-Key | Your apiKeyId. |
X-Timestamp | Current time in Unix epoch milliseconds, within ±5 minutes of server time. |
X-Signature | hex( 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.
Request
Section titled “Request”Pagination is cursor-based (the underlying store has no stable offset).
| Param | Required | Type | Default | Description |
|---|---|---|---|---|
tenantId | yes | string | — | Tenant to read. Must be in your allowed tenants. |
email | no | string | — | Look up a single holder by email (exact; case-insensitive). Returns 0 or 1 user. |
limit | no | number | 20 | Page size. Max 100 (larger values are clamped to 100). |
cursor | no | string | — | Opaque cursor from a previous response’s nextCursor. Omit for the first page. |
Example
Section titled “Example”# 1) Build the EXACT query string you will sendQS="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}"Response — 200 OK
Section titled “Response — 200 OK”{ "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="}users[]
Section titled “users[]”| Field | Type | Description |
|---|---|---|
email | string | Wallet holder email (normalized). |
balance | number | Current EP balance. |
walletStatus | string | Wallet status — ACTIVE or FROZEN. |
walletCreatedAt | string | null | When the wallet was first created (ISO-8601). |
hasAccount | boolean | true if a platform account exists for this email. |
name | string | null | Display name. null when no account. |
phone | string | null | Phone number. null when none. |
phoneVerified | boolean | Whether the phone is verified. Defaults to false. |
Top level
Section titled “Top level”| Field | Type | Description |
|---|---|---|
tenantId | string | Echoes the request. |
count | number | Number of users in this page. |
nextCursor | string | null | Opaque cursor for the next page; null on the last page. |
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) 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" } ] }}Reference implementation (Node.js)
Section titled “Reference implementation (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 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"));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. - Page until
nextCursorisnull(do not stop on a short page). - Treat
4xx(code) and200with a non-zeroerrorCodeboth as failures.