Credits & Wallets

Paygent's credit system lets you sell prepaid usage in custom credit currencies (for example Credits, API-Credits). Each customer holds a wallet per credit currency. Usage against credit-priced indicators debits the wallet automatically at billing time.

How it fits together

Credit currencies

Defined under Pricing → Credit currencies. Keys (e.g. Credits) are referenced in agent pricing, orders, and wallets.

Wallets

One active wallet row per (customer, credit currency, organization). Tracks available, pending, overage, and conversion rate (USD per credit).

Usage debits

When an indicator uses CREDITS billing, the tracking service debits creditsPerSignal from the matching wallet on each billed event. If the indicator has a linked billable metric, debits use metered_quantity × creditsPerSignal instead of one credit per event.

Credit-priced indicators

On an agent or plan, set an activity/outcome indicator's billing type to CREDITS. Configure:

Credit currency — which wallet currency to debit (must match a wallet the customer has).
Credits per indicator — how many credits each usage event costs (not a monthly fee).

Creating wallets

A customer needs an active wallet for each credit currency you intend to debit. There are two supported creation paths:

1. Manual creation (dashboard)

Use this for pilots, one-off top-ups, or customers without a subscription order yet.

Open Customers → [customer] → Wallet tab.
Click Create Wallet (first time) or Edit Wallet (add currencies to an existing logical wallet).
For each credit currency: set initial balance, conversion rate (default 0.01 = $0.01 per credit), rollover, and overage (credit line) settings.
Optionally enable Record as payment to log a synthetic payment for the USD value (credits × conversion_rate).

Dashboard API (session auth): POST /api/wallets/manual or POST /api/wallets/batch on the Paygent dashboard backend.

2. Through an order (subscription + platform fee credits)

Use this for production subscriptions where credits are bundled with platform fees on recurring invoices.

On the agent/plan Platform fee, add Credit benefits (currency + credit amount per billing period).
Create an Order for the customer. If the order includes credit benefits, configure per-currency wallet settings (rollover, overage allowed, overage limit) on the order lines step.
When an invoice is generated, the billing job creates wallets if missing and posts credits as pending (CREDIT_BENEFIT transactions).
When the invoice is marked paid (Confirm payment on the invoice or wallet flow), pending credits move to available balance and can be consumed.

Step-by-step order setup:

One wallet per currency

Manual and order-based wallets share the same database. You cannot have two active wallets for the same customer + credit currency + organization. Removing a currency in Edit Wallet deactivates it (active = false); re-adding the same currency reactivates that row.

Balances & overage

Field	Meaning
available_balance	Prepaid credits ready to spend on usage.
pending_balance	Credits granted on an invoice but not yet released (invoice unpaid).
overage_used / overage_limit	Temporary credit line when `overage_allowed` is true and prepaid is insufficient. Top-ups clear overage before adding to available balance.
conversion_rate	USD value of one credit (e.g. `0.01` → 100 credits = $1.00). Used for payment records and reporting.
rollover_enabled	When true, unused credits from a billing period can roll into the next period (processed on invoice allocation).

Wallet transaction types

Type	Description
CREDIT_BENEFIT	Credits from platform fee on an invoice (pending until paid).
CREDIT_TOPUP_DIRECT	Manual wallet creation, dashboard top-up, or API top-up.
DEBIT_USAGE	Usage consumed from prepaid balance (FIFO across credit blocks).
DEBIT_OVERAGE	Usage consumed against the overage credit line.
ROLLOVER	Unused credits moved into the next billing period.

When usage debits a wallet

During billing, if the customer has an active wallet for the indicator's credit currency:

If available_balance ≥ credits_required, debit prepaid only.
If prepaid is insufficient and overage_allowed, use prepaid first then overage up to overage_limit.
If no wallet exists, billing continues without wallet debit (normal revenue path).

Public Wallet API

Integrations can read balances and top up wallets via the Control Plane API (cp-tracking-service). Wallet creation is managed through the dashboard or order/invoice flows above—not via the public API.

Indicators & Usage-Based Pricing

Billable Metrics

Was this page helpful?

Need help? Contact us at support@withpaygent.com