Introduction

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

ConceptDescription
Credit currenciesDefined under Pricing → Credit currencies. Keys (e.g. Credits) are referenced in agent pricing, orders, and wallets.
WalletsOne active wallet row per (customer, credit currency, organization). Tracks available, pending, overage, and conversion rate (USD per credit).
Usage debitsWhen 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.

  1. Open Customers → [customer] → Wallet tab.
  2. Click Create Wallet (first time) or Edit Wallet (add currencies to an existing logical wallet).
  3. For each credit currency: set initial balance, conversion rate (default 0.01 = $0.01 per credit), rollover, and overage (credit line) settings.
  4. 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.

  1. On the agent/plan Platform fee, add Credit benefits (currency + credit amount per billing period).
  2. 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.
  3. When an invoice is generated, the billing job creates wallets if missing and posts credits as pending (CREDIT_BENEFIT transactions).
  4. 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: Orders & Invoicing

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

FieldMeaning
available_balancePrepaid credits ready to spend on usage.
pending_balanceCredits granted on an invoice but not yet released (invoice unpaid).
overage_used / overage_limitTemporary credit line when overage_allowed is true and prepaid is insufficient. Top-ups clear overage before adding to available balance.
conversion_rateUSD value of one credit (e.g. 0.01 → 100 credits = $1.00). Used for payment records and reporting.
rollover_enabledWhen true, unused credits from a billing period can roll into the next period (processed on invoice allocation).

Wallet transaction types

TypeDescription
CREDIT_BENEFITCredits from platform fee on an invoice (pending until paid).
CREDIT_TOPUP_DIRECTManual wallet creation, dashboard top-up, or API top-up.
DEBIT_USAGEUsage consumed from prepaid balance (FIFO across credit blocks).
DEBIT_OVERAGEUsage consumed against the overage credit line.
ROLLOVERUnused 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:

  1. If available_balance ≥ credits_required, debit prepaid only.
  2. If prepaid is insufficient and overage_allowed, use prepaid first then overage up to overage_limit.
  3. 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.

See Prepaid Wallets API or Postpaid Wallets API for full endpoint details.