Skip to content

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”
EndpointScopeReturns
…/ep/wallet-userstenantThe users that hold a wallet (one row per user).
…/ep/webhook/awardstenantYour partner awards across all users (AWARD_WEBHOOK only).
…/ep/code-redeemstenantEvery redeemed code in the tenant — which code, by whom, when.
…/ep/wallet-transactions ⭐one userEvery 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.

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-transactions.

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.

Returns one user’s EP ledger entries in a tenant, newest first, cursor-paginated.

ParamRequiredTypeDefaultDescription
tenantIdyesstring—Tenant to read. Must be in your allowed tenants.
emailyesstring—The user whose wallet you are reading (exact; case-insensitive).
directionnostring—Filter by CREDIT (điểm vào ví) or DEBIT (điểm ra khỏi ví).
typenostring—Filter by a single transaction type (see Transaction types).
fromnostring—ISO-8601 datetime. Include entries with createdAt >= from.
tonostring—ISO-8601 datetime. Include entries with createdAt <= to.
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&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}"
{
"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"
}

Current snapshot of the user’s wallet.

FieldTypeDescription
existsbooleanfalse if the user has no wallet yet (then transactions is empty).
balancenumberCurrent EP balance.
statusstringACTIVE or FROZEN.

Newest first.

FieldTypeDescription
epTransactionIdstringEP transaction id (one id = one DEBIT+CREDIT pair internally).
typestringTransaction type — see Transaction types.
directionstringCREDIT = points into the wallet, DEBIT = points out.
pointsnumberEP moved by this entry — always a positive integer; use direction for sign.
balanceAfternumber | nullWallet balance immediately after this entry.
refTypestring | nullWhat this entry references — e.g. ORDER, WEBHOOK, CODE.
refIdstring | nullThe referenced id (order id, your partner orderId, code id, …).
actorTypestring | nullWho triggered it — USER, PARTNER, ADMIN, SYSTEM.
actorIdstring | nullActor id (the user email, your partnerId, an admin id, …).
notestring | nullFree-text note attached to the entry.
createdAtstringISO-8601 timestamp.
typedirectionMeaning
AWARD_WEBHOOKCREDITPartner awarded EP via the webhook (điểm đối tác tích).
CODE_REDEEMCREDITUser redeemed a code (đổi mã nhận điểm).
VOTE_REFUNDCREDITA vote-by-EP was refunded.
VOTE_SPENDDEBITUser spent EP to vote.
CODE_EXPIREDEBITRedeemed points expired and were swept.
ADJUSTCREDIT/DEBITManual adjustment (carries a note).
FieldTypeDescription
tenantIdstringEchoes the request.
emailstringEchoes the request (normalized).
walletobjectCurrent wallet snapshot (see above).
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/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" } ] }
}
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);
  • 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; email is required.
  • points is always positive — read direction to know in vs out.
  • 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.