Skip to main content

Admin USD Wallet Transaction Detail View

Goal: add a detail screen for each row in Admin > USD Wallets so admins can:

  • view complete transaction data (not only in/out direction),
  • make faster approve/reject decisions for pending withdrawals,
  • debug balance/fee/reversal discrepancies.

Data Scope Reviewed​

  • The admin list currently reads from API GET /admin/usd-wallets/ledger.
  • Each ledger row is a UsdWalletTransaction record with usdWallet relation.
  • Main field sources:
    • kioskgaming_backend/src/database/models/UsdWalletTransaction.js
    • kioskgaming_backend/src/controllers/admin/usdWalletManagementController.js
    • kioskgaming_backend/src/controllers/shop/shopUsdWalletController.js
    • kioskgaming_backend/src/controllers/agent/agentUsdWalletController.js
    • kioskgaming_backend/src/controllers/superAgent/superAgentUsdWalletController.js
    • kioskgaming_backend/src/services/core/depositSettlementCoreService.js

Target Users​

  • Finance operations admins.
  • Withdrawal approval admins.
  • Technical admins investigating ledger/metadata consistency.

UX Principle: Avoid Raw IDs as Primary Display​

Raw IDs are useful for debugging, but they should not be the primary surface for operational users. For day-to-day workflows, the UI should prioritize human-readable labels and keep technical IDs secondary.

Recommended principle:

  • Primary line: human-readable identity (name, email, phone, short transaction code).
  • Secondary line: technical identifier (id, UUID, wallet id) in smaller monospace text.
  • Always provide copy for technical IDs, but do not force users to read them first.
  1. Open Admin > USD wallets.
  2. Filter by owner/date and click Load.
  3. In the Actions column, click View on the target row.
  4. Open Transaction detail (modal or dedicated page).
  5. Review sections in this order:
    • Header (transaction identity),
    • Money (amounts and balance snapshots),
    • Reference (linked transaction context),
    • Operational (payout/admin decision),
    • Raw metadata (deep debugging).
  6. If the transaction is a pending withdrawal, proceed to Approve/Reject.

Fields to Display on Transaction Detail​

1) Identity + Owner (Always Visible)​

  • id (UUID ledger row)
  • transactionId (idempotency/business transaction id)
  • type (deposit | withdrawal | adjustment | reversal)
  • status (pending | completed | failed | cancelled)
  • provider
  • referenceType
  • referenceId
  • usdWallet.id
  • usdWallet.ownerType
  • usdWallet.ownerId
  • usdWallet.currency
  • createdAt
  • updatedAt

Display guidance:

  • Put transactionId in a prominent position with a one-click copy control (icon).
  • Render type and status as color badges (green/red/amber/gray).
  • Provide owner navigation link (shop/agent/super-agent) when route mapping exists.
  • Do not show ownerId alone. Show display text first, e.g.:
    • Shop Β· Lucky Star (shop@...)
    • Agent Β· John Doe (+1-***-***-1234)
    • Super agent Β· Alpha Group
  • Keep ownerId as secondary/debug text only.

2) Amount + Balance Snapshot (Always Visible)​

  • amountGross
  • amountNet
  • balanceGrossBefore
  • balanceGrossAfter
  • balanceNetBefore
  • balanceNetAfter

Display guidance:

  • Show both formatted values and raw values (for debugging precision issues).
  • Show visual delta sign (+/-) based on type.
  • Add summary lines:
    • Net change: balanceNetAfter - balanceNetBefore
    • Gross change: balanceGrossAfter - balanceGrossBefore

3) Common Metadata (Render if Key Exists)​

  • metadata.note
  • metadata.createdBy
  • metadata.source
  • metadata.matchedFeeMethodId

Display guidance:

  • Render dynamically by existing keys (do not hardcode one shape).
  • Long values should support expand/collapse.

4) Portal Withdrawal-Specific Metadata​

Applies to type=withdrawal rows (especially pending/completed/cancelled):

  • metadata.payoutNetwork
  • metadata.payoutWalletAddress
  • metadata.requestedNetUsd
  • metadata.computedFeeRate
  • metadata.computedFeeUsd
  • metadata.computedGrossDebitUsd

Display guidance:

  • Group these into a Withdrawal payout info section.
  • Add copy control for payoutWalletAddress.
  • Show fee as both percentage and USD amount.

5) Admin Decision Metadata (Approve/Reject)​

  • metadata.adminApproval.approvedAt
  • metadata.adminApproval.approvedByAdminId
  • metadata.adminApproval.note
  • metadata.adminRejection.rejectedAt
  • metadata.adminRejection.rejectedByAdminId
  • metadata.adminRejection.note

Display guidance:

  • Split into small Approval and Rejection blocks.
  • If both are missing, show: No admin decision yet.

6) Reversal Metadata for Rejected Withdrawal​

For type=reversal rows (created by admin rejection):

  • metadata.sourceWithdrawalId
  • metadata.sourceWithdrawalTransactionId
  • metadata.note

Display guidance:

  • Show backlink to source withdrawal if route exists.
  • Add label: Auto-generated reversal.

7) Deposit Settlement Metadata (Payer Side)​

Common on type=deposit rows:

  • metadata.feeKnown
  • metadata.platformFeeAmount
  • metadata.platformFeeRate
  • metadata.originalCurrency
  • metadata.buyerType
  • metadata.buyerId
  • metadata.creditComputed
  • metadata.costRateAtPurchase
  • metadata.usedCallbackNetUsd
  • metadata.receivedNetUsd

Display guidance:

  • Group under a Settlement snapshot section.
  • Add tooltips for technical keys such as usedCallbackNetUsd.

Detailed UI Proposal (User Guidance)​

A. Header bar (sticky if full page)​

  • Left: Type badge + Status badge.
  • Center: transactionId (monospace + copy icon control).
  • Right: CreatedAt, UpdatedAt, Back button.

UX objective:

  • Admin identifies the transaction and current state in under 2 seconds.

B. Section "Owner & Context"​

  • Show:
    • Owner type, owner id, currency.
    • Wallet id.
    • Provider.
  • Add Open owner profile if route mapping exists.

UX objective:

  • Quickly confirm ownership and avoid acting on the wrong account.

C. Section "Money Movement" (Most Important)​

  • Card 1: Amount (amountGross, amountNet).
  • Card 2: Before balance (balanceGrossBefore, balanceNetBefore).
  • Card 3: After balance (balanceGrossAfter, balanceNetAfter).
  • Card 4: Delta (gross/net).

UX objective:

  • Let admins validate before/after balances at a glance.

D. Section "Reference"​

  • referenceType, referenceId.
  • Deep-link / embed when referenceType = payment_transaction (see catalog below: inline detail + optional β€œopen full page”).
  • If no route mapping, provide a copy control (icon button with tooltip / aria-label) for referenceId.

UX objective:

  • Jump quickly to related source transaction for investigation.

Display refinement for end users:

  • Prefer business-friendly label over raw reference id when possible:
    • Example: Payment transaction #PTX-2026-000123 instead of UUID-only.
  • Show full raw referenceId only in expandable debug row or tooltip.

E. Section "Operational Details" (conditional)​

  • Render only when relevant keys exist:
    • Withdrawal payout info (network/address/fee).
    • Admin decision (approve/reject).
    • Settlement snapshot (deposit settlement metadata).
    • Reversal trace (source withdrawal).

UX objective:

  • Reduce noise by showing only data-backed blocks.

F. Section "Raw Metadata JSON"​

  • JSON viewer read-only.
  • Include copy-as-JSON control (icon + accessible label, e.g. β€œCopy metadata as JSON”) + Expand all where supported.
  • Place at the bottom.

UX objective:

  • Support deep technical debugging without disrupting primary review flow.

Field Rendering Rules​

  • Do not hardcode one schema; prefer key-existence rendering.
  • Mandatory blocks: identity, owner, amounts, balance snapshots, timestamps.
  • Metadata is optional: render only existing keys.
  • Long strings (payoutWalletAddress, notes) must support wrap + copy.
  • Numeric formatting should be consistent:
    • UI display: 2-8 decimals depending on field.
    • Hover/tooltip: full raw value.

Identity display rules (important):

  • Never use UUID as the only visible identity in primary rows/cards.
  • Default label priority for owner:
    1. name
    2. email
    3. masked phone
    4. short-form id (only if no better identity exists)
  • Keep full IDs in:
    • copy control (icon + label),
    • tooltip,
    • debug section (Raw metadata / Technical details).

Masking guidance:

  • Email: partially masked in dense table context (full in detail if permission allows).
  • Phone: masked by default (***), full value only for authorized roles.

States and User Messages​

  • Loading: section-level skeletons (avoid full-page blocking if previous data exists).
  • Not found: "Transaction does not exist or has been archived."
  • No metadata: "No additional metadata recorded."
  • Permission denied: "You do not have permission to view this transaction detail."

Suggested Microcopy​

  • Title: USD Wallet Transaction Detail
  • Subtitle: Review amounts, balances, references, and operational metadata.
  • Copy success toast: Copied to clipboard.
  • Empty block: No data available for this section.
  • Technical row label: Technical ID
  • Human label row: Display name

Reference Type Catalog (Display Reference)​

The following catalog defines each known referenceType, business meaning, and how the UI should display it.

1) payment_transaction​

  • Business meaning:
    • USD wallet ledger row is linked to a payment transaction flow (deposit/withdrawal/settlement source).
  • Display reference:
    • Primary label: Payment transaction
    • Secondary: technical referenceId (copyable).
  • Navigation:
    • Prefer inline embed in the same USD wallet transaction detail panel: call GET /admin/transactions/:id with id = referenceId (numeric internal id) and render the same payment-transaction detail cards used on the full transaction page (variant="embedded"), so admins see ledger + linked flow without leaving the modal.
    • Keep a secondary action: deep link /transactions/:referenceId (β€œOpen full page”) for bookmarking, sharing, or side-by-side review.

2) balance_to_credits​

  • Business meaning:
    • Ledger relates to converting balance into credits.
  • Display reference:
    • Primary label: Balance to credits
    • Secondary: technical referenceId.
  • Navigation:
    • No direct route mapping currently.

3) usd_wallet_transaction​

  • Business meaning:
    • Ledger row references another USD wallet transaction (common in reversal/chained operations).
  • Display reference:
    • Primary label: USD wallet transaction
    • Secondary: technical referenceId.
  • Navigation:
    • If/when detail route exists, should point to USD wallet transaction detail by id.
    • Current state: text + copy only.

4) balance_to_credits_settlement​

  • Business meaning:
    • Settlement stage for balance-to-credits process.
  • Display reference:
    • Primary label: Balance to credits settlement
    • Secondary: technical referenceId.
  • Navigation:
    • No route mapping currently.

5) usd_withdrawal_request​

  • Business meaning:
    • Row created from online-balance USD withdrawal request (portal initiated).
  • Display reference:
    • Primary label: USD withdrawal request
    • Secondary: technical referenceId.
  • Navigation:
    • No dedicated route mapping currently.
    • Operational details are mainly read from metadata (payoutNetwork, payoutWalletAddress, fee fields).

6) online_debt_settlement​

  • Business meaning:
    • Related to online debt settlement workflow.
  • Display reference:
    • Primary label: Online debt settlement
    • Secondary: technical referenceId.
  • Navigation:
    • No direct route mapping currently.

7) admin_shop_adjustment​

  • Business meaning:
    • Admin-triggered shop adjustment flow.
  • Display reference:
    • Primary label: Admin shop adjustment
    • Secondary: technical referenceId.
  • Navigation:
    • No direct route mapping currently.

8) hierarchy_withdrawal​

  • Business meaning:
    • Withdrawal within hierarchy flow (agent/super-agent tier withdrawal handling).
  • Display reference:
    • Primary label: Hierarchy withdrawal
    • Secondary: technical referenceId.
  • Navigation:
    • No direct route mapping currently.

9) null / empty reference type​

  • Business meaning:
    • Source reference not recorded or not applicable for that row.
  • Display reference:
    • Primary label: Reference
    • Secondary: show referenceId only if present, otherwise β€”.
  • Navigation:
    • No deep link.

UI rule for all reference types​

  • Always show human-readable label first (primary).
  • Keep raw referenceId as technical secondary row with a copy control (prefer icon + aria-label / title over large text buttons).
  • Only render deep link / inline embed for types explicitly mapped (currently payment_transaction for embed + full page).
  • Unknown or legacy referenceType values (including rows written before a reference convention changed) should auto-fallback to:
    • primary label = referenceType transformed from snake_case (or Reference when empty),
    • secondary = raw referenceId.

API for Detail View​

Current option (reuse list payload):

  • Open modal/page detail directly from selected list row data.

If you need dedicated API for SSR/deep-link:

  • Add endpoint GET /admin/usd-wallets/ledger/:id returning:
    • full UsdWalletTransaction fields,
    • relation usdWallet
    • (optional) resolved owner display name (shop/agent/super-agent) to reduce extra calls.

UI Implementation Checklist (Suggested)​

  • Detail route or detail modal is accessible from list.
  • All always-visible fields are rendered.
  • Metadata rendering is dynamic by key existence.
  • Copy controls (e.g. icon buttons with labels) exist for transactionId, referenceId, walletAddress, raw JSON.
  • Deep-link is available for mapped referenceType.
  • Clear loading/error/not-found states are implemented.
  • Color badges exist for type and status.
  • Layout is responsive (desktop and small laptop widths).
  • Owner and reference are shown with human-readable labels first; raw IDs are secondary.
  • Masking and permission-based visibility are applied for sensitive contact fields.