Credits & Wallets

Paygent bills usage in custom credit currencies (e.g. cx). Each customer has one wallet per currency. Choose prepaid (credits loaded upfront) or postpaid (usage accrues, invoiced later). The setup path differs for each—see the sections below.

Credit currencies (shared first step)

Before prepaid or postpaid, define your credit currency under Credit Currencies in the sidebar:

Name / key — e.g. cx (used everywhere: agent pricing, wallets, API).
Default conversion rate — USD per credit (e.g. 0.002 → 100 credits = $0.20 at invoice time).

You create the currency once. Prepaid and postpaid both reference this same key—but they wire it in different places (platform fee vs activity indicator).

Prepaid wallets

Customer pays before usage. Credits are loaded into available_balance via platform-fee benefits, manual top-up, or order invoice. Usage debits that balance.

Where credits come from (prepaid)

Prepaid credits are primarily granted through the agent's Platform fee → Credit benefits:

On the agent/plan Platform fee, enable Credits / Entitlement.
Choose the credit currency (e.g. cx) and set how many credits the customer receives per billing period (e.g. 1000 credits/month).
Set indicator pricing to CREDITS with the same currency and credits per indicator (cost per usage event).
Create an Order for the customer. On the order, configure prepaid wallet settings (rollover, overage) if needed.
When an invoice runs, credits post as pending. After payment is confirmed, they move to available and can be spent.

Platform fee = credit load, indicator = usage cost

Platform fee credit benefits define how many credits the customer receives each period. Activity indicator credits per signal define how many credits each usage event costs. Both use the same credit currency key.

Create a prepaid wallet

Option A — via order (recommended for subscriptions)

Wallet is auto-created on first invoice when platform fee credit benefits exist. Configure rollover/overage on the order's wallet settings step.

Option B — manual (dashboard)

Customers → [customer] → Wallet → Create Wallet.
Choose Prepaid wallet.
Add credit currency, initial balance, conversion rate, rollover, and overage settings.

Prepaid balance fields

Field	Meaning
available	Credits ready to spend.
pending	Credits from unpaid invoice (platform fee benefit).
overage_used / overage_limit	Optional credit line when prepaid runs out.

On each usage event, credits are debited from available (or overage if enabled). Blocked when balance + overage are exhausted.

Postpaid wallets

Customer uses the service first, pays at period end. No upfront credit load. Usage accrues in postpaid_used and is invoiced in USD using the wallet conversion rate.

How pricing works (postpaid)

Postpaid does not use platform-fee credit benefits to load credits. You price usage directly on the activity indicator:

On the agent Activity based section, open your indicator (e.g. per_minute).
Set Billing type to Credits.
Choose the credit currency directly (e.g. cx)—this is the currency you created under Credit Currencies.
Set Credits per indicator — how many credits one usage event costs (e.g. 10 credits per call).

No platform fee credits needed

For postpaid, you do not need to add credit benefits on the Platform fee (credits can stay at 0). The indicator's credits per indicator + credit currency selection is enough. Each POST /api/v2/usage event accrues that amount on the customer's postpaid wallet.

Create a postpaid wallet

Postpaid wallets are created in the dashboard only (not via order auto-creation or public API).

Customers → [customer] → Wallet → Create Wallet.
Choose Postpaid wallet.
Add the same credit currency you chose on the indicator (e.g. cx). Conversion rate is inherited from the currency definition.
Optionally set a credit limit (0 = unlimited). No initial balance required.
Create an Order for billing period / invoicing so usage is invoiced at period end.

Create postpaid wallet before first invoice

If the order's platform fee also lists a credit benefit for the same currency, invoice cron may auto-create a prepaid wallet first. For postpaid-only setups, create the postpaid wallet manually before the first invoice, and avoid granting platform-fee credits on that currency.

Postpaid balance fields

Field	Meaning
postpaid_used	Credits accrued this billing period (resets after invoice).
postpaid_limit	Hard stop (0 = no limit).

available stays 0 on postpaid—always check postpaid_used before allowing more usage.

At invoice time: accrued credits × conversion rate → invoice line in USD. postpaid_used resets to 0 for the next period.

At a glance

	Prepaid	Postpaid
Where you set the currency	Platform fee credit benefits + indicator	Activity indicator only (pick currency + credits per indicator)
How credits enter the wallet	Platform fee benefit, top-up, manual initial balance	They don't—usage accrues as debt
Wallet creation	Order auto-create or manual prepaid	Manual postpaid only (dashboard)
Check before usage (API)	`available`	`postpaid_used` vs `postpaid_limit`

Wallet transaction types

Type	Wallet	Description
CREDIT_BENEFIT	Prepaid	Credits from platform fee on invoice (pending until paid).
CREDIT_TOPUP_DIRECT	Prepaid	Manual top-up or API top-up.
DEBIT_USAGE	Prepaid	Usage from prepaid balance.
DEBIT_OVERAGE	Prepaid	Usage against credit line.
DEBIT_POSTPAID	Postpaid	Usage accrued (increases postpaid_used).
ROLLOVER	Prepaid	Unused credits carried to next period.

One wallet per currency

One active wallet per customer + credit currency + organization. You cannot mix prepaid and postpaid for the same currency on one customer—choose one type when creating the wallet.

Indicators & Usage-Based Pricing

Billable Metrics

Was this page helpful?

Need help? Contact us at support@withpaygent.com