Partner API — EP wallet transactions (per user)
Read a single user’s full EP wallet history — every point movement into and out of the wallet, not just partner awards. 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-transactions
How this differs from the other partner reads
Section titled “How this differs from the other partner reads”| Endpoint | Scope | Returns |
|---|---|---|
…/ep/wallet-users | tenant | The users that hold a wallet (one row per user). |
…/ep/webhook/awards | tenant | Your partner awards across all users (AWARD_WEBHOOK only). |
…/ep/code-redeems | tenant | Every redeemed code in the tenant — which code, by whom, when. |
…/ep/wallet-transactions ⭐ | one user | Every EP movement on that user’s wallet (all types, both directions). |
Use this endpoint when you have a specific user (by email) and want their complete EP statement: awards, code redemptions, votes spent, refunds, expiries, and manual adjustments.
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-transactions.
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”Returns one user’s EP ledger entries in a tenant, newest first, cursor-paginated.
| Param | Required | Type | Default | Description |
|---|---|---|---|---|
tenantId | yes | string | — | Tenant to read. Must be in your allowed tenants. |
email | yes | string | — | The user whose wallet you are reading (exact; case-insensitive). |
direction | no | string | — | Filter by CREDIT (điểm vào ví) or DEBIT (điểm ra khỏi ví). |
type | no | string | — | Filter by a single transaction type (see Transaction types). |
from | no | string | — | ISO-8601 datetime. Include entries with createdAt >= from. |
to | no | string | — | ISO-8601 datetime. Include entries with createdAt <= to. |
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&email=alice%40example.com&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-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”{ "tenantId": "7g1RP3", "email": "alice@example.com", "wallet": { "exists": true, "balance": 4906, "status": "ACTIVE" }, "transactions": [ { "epTransactionId": "149d8487-fe6a-4ff7-b5ea-f2c89a752fed", "type": "VOTE_SPEND", "direction": "DEBIT", "points": 20, "balanceAfter": 4906, "refType": "ORDER", "refId": "eT7J4q23e7Vc", "actorType": "USER", "actorId": "alice@example.com", "note": null, "createdAt": "2026-06-27T17:33:12.438Z" }, { "epTransactionId": "b1f0…award", "type": "AWARD_WEBHOOK", "direction": "CREDIT", "points": 5000, "balanceAfter": 5150, "refType": "WEBHOOK", "refId": "test_1781684660441_29cf44", "actorType": "PARTNER", "actorId": "demo", "note": null, "createdAt": "2026-06-17T08:24:21.264Z" } ], "nextCursor": "eyJ3YWxsZXRJZCI6IlVTRVIjN2cxUlAzI2FsaWNlQGV4YW1wbGUuY29tIiwiU0siOiIyMDI2LTA2LTE3VDA4OjI0OjIxLjI2NFojYjFmMCJ9"}wallet
Section titled “wallet”Current snapshot of the user’s wallet.
| Field | Type | Description |
|---|---|---|
exists | boolean | false if the user has no wallet yet (then transactions is empty). |
balance | number | Current EP balance. |
status | string | ACTIVE or FROZEN. |
transactions[]
Section titled “transactions[]”Newest first.
| Field | Type | Description |
|---|---|---|
epTransactionId | string | EP transaction id (one id = one DEBIT+CREDIT pair internally). |
type | string | Transaction type — see Transaction types. |
direction | string | CREDIT = points into the wallet, DEBIT = points out. |
points | number | EP moved by this entry — always a positive integer; use direction for sign. |
balanceAfter | number | null | Wallet balance immediately after this entry. |
refType | string | null | What this entry references — e.g. ORDER, WEBHOOK, CODE. |
refId | string | null | The referenced id (order id, your partner orderId, code id, …). |
actorType | string | null | Who triggered it — USER, PARTNER, ADMIN, SYSTEM. |
actorId | string | null | Actor id (the user email, your partnerId, an admin id, …). |
note | string | null | Free-text note attached to the entry. |
createdAt | string | ISO-8601 timestamp. |
Transaction types
Section titled “Transaction types”type | direction | Meaning |
|---|---|---|
AWARD_WEBHOOK | CREDIT | Partner awarded EP via the webhook (điểm đối tác tích). |
CODE_REDEEM | CREDIT | User redeemed a code (đổi mã nhận điểm). |
VOTE_REFUND | CREDIT | A vote-by-EP was refunded. |
VOTE_SPEND | DEBIT | User spent EP to vote. |
CODE_EXPIRE | DEBIT | Redeemed points expired and were swept. |
ADJUST | CREDIT/DEBIT | Manual adjustment (carries a note). |
Top level
Section titled “Top level”| Field | Type | Description |
|---|---|---|
tenantId | string | Echoes the request. |
email | string | Echoes the request (normalized). |
wallet | object | Current wallet snapshot (see above). |
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/email, malformed
from/to) return HTTP 200 with a non-zero errorCode:
{ "errorCode": 100400, "message": "Dữ liệu không hợp lệ", "data": { "params": [ { "path": "email", "message": "email 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 listWalletTransactions(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-transactions?${queryString}`, { headers: { "X-Api-Key": API_KEY_ID, "X-Timestamp": timestamp, "X-Signature": signature, }, }, ); return res.json();}
// Pull a user's entire EP statement (every page).async function fullStatement(tenantId, email) { const all = []; let cursor; do { const params = { tenantId, email, limit: "100", ...(cursor ? { cursor } : {}) }; const page = await listWalletTransactions(params); all.push(...page.transactions); cursor = page.nextCursor; } while (cursor); return all;}
// Only the credits (điểm vào ví):listWalletTransactions({ tenantId: "7g1RP3", email: "alice@example.com", direction: "CREDIT" }) .then(console.log);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;emailis required. -
pointsis always positive — readdirectionto know in vs out. - Page until
nextCursorisnull(do not stop on a short page). - Treat
4xx(code) and200with a non-zeroerrorCodeboth as failures.