Introduction

Credits & Wallets

Paygent bills usage in custom credit currencies (e.g. cx, Credits). Each customer holds one wallet per currency. Usage against credit-priced indicators debits or accrues on that wallet at billing time.

Choose prepaid (pay before use) or postpaid (use now, invoice later). The setup path differs — read both sections before configuring.

Prepaid vs postpaid

PrepaidPostpaid
Payment modelCustomer pays upfrontCustomer pays at period end
Where currency is setPlatform fee credit benefits + indicatorActivity indicator only
How credits enter walletPlatform fee benefit, top-up, manual balanceThey don’t — usage accrues as debt
Wallet creationOrder auto-create or manual prepaidManual postpaid only (dashboard)
Check before usage (API)available_balancepostpaid_used vs postpaid_limit
Primary balance fieldavailable_balancepostpaid_used

One wallet per currency. You cannot mix prepaid and postpaid for the same customer + credit currency + organization. Choose the wallet type when creating it — before the first invoice.

Prepaid wallets

Customer pays before usage. Credits load into available_balance via platform-fee benefits, manual top-up, or order invoice payment.

Where credits come from

  1. On the agent/plan Platform fee, enable Credits / Entitlement
  2. Choose the credit currency and credits per billing period (e.g. 1,000/month)
  3. Set indicator pricing to CREDITS with the same currency and credits per indicator
  4. Create an Order — configure wallet settings (rollover, overage) on the Lines step
  5. Invoice runs → credits post as pending → Mark as paid → credits become available

Platform fee = credit load. Indicator = usage cost. Platform fee credit benefits define how many credits the customer receives. Indicator credits per signal defines how many each usage event costs.

Create a prepaid wallet

Option A — via order (recommended)

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

Option B — manual (dashboard)

  1. Customers → [customer] → Wallet → Create Wallet
  2. Choose Prepaid wallet
  3. Add credit currency, initial balance, conversion rate, rollover, and overage settings
  4. Optionally enable Record as payment to log USD value

Prepaid balance fields

FieldMeaning
available_balanceCredits ready to spend
pending_balanceCredits from unpaid invoice (platform fee benefit)
overage_used / overage_limitOptional credit line when prepaid is insufficient
conversion_rateUSD per credit for invoicing and reporting
rollover_enabledUnused credits carry to next period

On each usage event, credits debit 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 does not use platform-fee credit benefits. Price usage on the activity indicator:

  1. Agents → Activity based → open indicator
  2. Set billing type to CREDITS
  3. Choose the credit currency (from Credit Currencies)
  4. Set credits per indicator — cost per usage event

Each 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):

  1. Customers → [customer] → Wallet → Create Wallet
  2. Choose Postpaid wallet
  3. Add the same credit currency used on the indicator
  4. Optionally set credit limit (0 = unlimited)
  5. Create an Order for billing period / invoicing

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 platform-fee credits on that currency.

Postpaid balance fields

FieldMeaning
postpaid_usedCredits accrued this billing period (resets after invoice)
postpaid_limitHard stop (0 = no limit)

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

At invoice time: postpaid_used × conversion_rate → USD line item. Balance resets for the next period.

Credit-priced indicators

On an agent or plan, set an indicator’s billing type to CREDITS:

  • Credit currency — which wallet to debit (must match an existing wallet)
  • Credits per indicator — cost per event (or metered_quantity × creditsPerSignal with a billable metric)

Wallet transaction types

TypeWalletDescription
CREDIT_BENEFITPrepaidCredits from platform fee (pending until paid)
CREDIT_TOPUP_DIRECTPrepaidManual or API top-up
DEBIT_USAGEPrepaidUsage from prepaid balance
DEBIT_OVERAGEPrepaidUsage against credit line
DEBIT_POSTPAIDPostpaidUsage accrued (increases postpaid_used)
ROLLOVERPrepaidUnused credits moved to next period

When usage debits a wallet

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

  1. Prepaid: If available_balance ≥ credits_required, debit prepaid. If insufficient and overage_allowed, use prepaid first then overage up to overage_limit.
  2. Postpaid: Accrue credits on postpaid_used; convert to USD on invoice.
  3. No wallet: Billing continues on the normal revenue path without wallet debit.

Public Wallet API

Integrations can read balances and top up prepaid wallets via the Control Plane API. Wallet creation is managed through the dashboard or order/invoice flows — not via the public API.