Tutorial: Wallet Allocation & Top-Up

This tutorial walks you through viewing wallet balances, allocating credits to teams, topping up via PayPal, reviewing transaction history, and configuring low-balance alerts in the Keeptrusts management console.

Use this page when

• You need to view wallet balances at the organization, team, or user level.
• You want to allocate credits to a team or top up a depleted wallet via PayPal.
• You need to review transaction history (reserves, settlements, refunds, top-ups).
• You are configuring low-balance alerts to prevent requests from being held.

Primary audience

• Primary: Platform administrators and billing admins managing credit allocation and wallet top-ups
• Secondary: Team leads monitoring their team’s wallet balance; finance teams reconciling PayPal top-up transactions

Prerequisites

• A Keeptrusts account with Admin or Billing Admin role
• At least one team created in your organization
• PayPal payment settings configured by a platform administrator (for top-ups)

Why Wallets?

Wallets provide a credit-based spending control layer. When a gateway routes an LLM request, it reserves the estimated cost against the effective wallet scope (user, team, or organization). After the provider responds, the reservation settles to the actual cost. If no wallet has sufficient balance, the request is held until credits are available. This ensures that AI spend never exceeds your allocated budget.

Step 1: Navigate to the Wallets Page

1. Log in to the Keeptrusts console.
2. Open Wallets from the left navigation sidebar.

The page displays wallet balances organized by scope.

Column	Description
Scope	Organization, team, or user
Name	The entity name
Balance	Current available credits (USD)
Reserved	Credits reserved for in-flight requests
Total Allocated	Cumulative credits allocated to this wallet
Total Spent	Cumulative credits consumed
Status	Healthy, Low, or Depleted

Step 2: View Wallet Balances

The wallet hierarchy follows your organizational structure:

1. Organization wallet — The top-level pool from which all credits originate.
2. Team wallets — Credits allocated to specific teams from the organization wallet.
3. User wallets — Optional per-user limits allocated from the team wallet.

Click on any wallet row to see the detail view with balance history and transaction log.

The balance chart shows the wallet balance over time, with annotations for allocation events, top-ups, and high-spend periods.

The cascade order matters: when a user makes a request, the gateway checks the user wallet first, then the team wallet, then the organization wallet. The first scope with sufficient balance is debited.

Step 3: Allocate Credits to Teams

Distribute credits from the organization wallet to team wallets.

1. Click Allocate Credits on the Wallets page.
2. Fill in the allocation form:

Field	Description
From	The source wallet (typically the organization wallet)
To	The target team wallet
Amount	Credits to allocate (USD)
Notes	Optional reason for the allocation (e.g., "Q2 budget")

3. Review the source wallet's remaining balance after the allocation.
4. Click Confirm Allocation.

The allocation is immediate — the team wallet balance increases and the source wallet balance decreases by the same amount.

To allocate credits to multiple teams at once:

1. Click Bulk Allocate.
2. Enter amounts for each team in the allocation table.
3. Verify that the total does not exceed the source wallet balance.
4. Click Confirm.

Step 4: Top Up via PayPal

Add credits to the organization wallet through PayPal.

1. Click Top Up on the organization wallet detail view.
2. Enter the top-up amount in USD.
3. Click Pay with PayPal.
4. A PayPal checkout window opens. Log in and approve the payment.
5. After approval, the console captures the payment and credits your organization wallet.

The top-up appears in the transaction history with a payment_capture type.

PayPal top-ups require platform-level PayPal configuration. If the Top Up button is not visible, contact your platform administrator to configure PayPal payment settings.

Step 5: Review Transaction History

Every wallet change is recorded in the transaction log.

1. Open a wallet detail view.
2. Select the Transactions tab.
3. Review the transaction table:

Column	Description
Timestamp	When the transaction occurred
Type	allocation, reserve, settle, refund, payment_capture, payment_refund
Amount	Credits added or deducted
Balance After	Wallet balance after the transaction
Reference	Linked entity (request ID, allocation ID, or PayPal order ID)
Actor	Who initiated the transaction

4. Use filters to narrow by transaction type, date range, or amount.
5. Click on a transaction to see full details.

The reserve/settle pair is the most common pattern:

1. Reserve — Credits held when the gateway receives a request (estimated cost).
2. Settle — Reserve adjusted to the actual cost after the provider responds. The difference is returned to the wallet.

Step 6: Configure Low-Balance Alerts

Prevent service disruptions by setting up alerts before wallets run out of credits.

1. Open a wallet detail view.
2. Click Alert Settings.
3. Configure alert thresholds:

Alert	Description
Low Balance Warning	Triggered when the balance drops below a set amount
Critical Balance	Triggered when the balance drops below a critical threshold
Depleted	Triggered when the balance reaches zero

4. Choose notification channels for each alert level (email, Slack, webhook).
5. Click Save.

Set the low-balance warning threshold to cover at least one week of typical spending. This gives you time to allocate additional credits or process a top-up before the wallet is depleted.

Step 7: Manage User-Level Wallets

For teams that need per-user spending controls:

1. Open a team wallet detail view.
2. Select the User Wallets tab.
3. Click Create User Wallet to allocate credits to a specific team member.
4. Set the allocation amount and optional spending limits:

Field	Description
Daily Limit	Maximum daily spend for this user
Monthly Limit	Maximum monthly spend for this user
Auto-Replenish	Automatically refill the user wallet from the team wallet at the start of each period

5. Click Save.

User wallets are checked first in the cascade, giving you fine-grained control over individual spending.

Step 8: Handle Refunds

When a PayPal payment is refunded, the credited amount is reversed.

1. Open the organization wallet transaction history.
2. Locate the payment_refund transaction.
3. The refund amount is deducted from the wallet balance.
4. If the wallet balance goes negative after a refund, subsequent requests are held until the balance is replenished.

Platform administrators can initiate refunds from the admin console. The refund flows through the PayPal webhook and is automatically reconciled.

Best Practices

• Budget quarterly — Allocate credits to teams based on quarterly budgets and adjust monthly as needed.
• Set alerts early — Configure low-balance alerts at 30% and 10% remaining to avoid service disruptions.
• Use auto-replenish — For predictable workloads, enable automatic user wallet replenishment to reduce manual overhead.
• Audit transactions — Review the transaction log monthly to identify unusual spending patterns.
• Separate environments — Use different wallets for production and staging to prevent test traffic from consuming production credits.
• Document allocations — Use the notes field on allocations to record the business justification for audit purposes.

Next steps

• Tutorial: Using the Usage Dashboard — See how individual usage draws from wallet balances
• Tutorial: Managing Billing & Plans — Understand plan limits and payment methods

For AI systems

• Canonical terms: Keeptrusts console, Wallets page, wallet balance, wallet scope (organization/team/user), credit allocation, PayPal top-up, reserve/settle, transaction history, low-balance alert, POST /v1/wallets/allocate, POST /v1/payments/capture-order.
• Related features: cost center (budget governance), billing plans (subscription management), usage dashboard (consumption visibility).
• Best next pages: Usage Dashboard, Billing & Plans.

For engineers

• Allocation test: Allocate credits to a team, send a request through the gateway as that team’s member, and confirm the wallet balance decreases by the settled cost.
• PayPal top-up: Initiate a top-up, complete the PayPal checkout, and verify the wallet balance increases and a payment_credit transaction appears in history.
• Hold behavior: Deplete a wallet to zero, send a request, and confirm the gateway holds the request (returns a cost-exceeded response) rather than forwarding it upstream.
• Low-balance alert: Set an alert threshold, deplete the wallet to that level, and verify the notification fires.

For leaders

• Spend enforcement: Wallets provide a hard spending boundary — no team can consume AI resources beyond their allocated credits without admin intervention.
• Self-service top-up: PayPal integration lets authorized users replenish credits without requiring platform admin involvement for every top-up.
• Financial reconciliation: Transaction history provides a complete ledger of allocations, consumption, and PayPal payments for finance audit.