> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withpaygent.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpaygent.com/_mcp/server.

# Credits & Wallets

Paygent bills usage in custom [credit currencies](/documentation/introduction/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

|                              | Prepaid                                      | Postpaid                            |
| ---------------------------- | -------------------------------------------- | ----------------------------------- |
| **Payment model**            | Customer pays upfront                        | Customer pays at period end         |
| **Where currency is set**    | Platform fee credit benefits + indicator     | Activity indicator only             |
| **How credits enter wallet** | Platform fee benefit, top-up, manual 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_balance`                          | `postpaid_used` vs `postpaid_limit` |
| **Primary balance field**    | `available_balance`                          | `postpaid_used`                     |

> **Warning**
>
> **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](/documentation/introduction/credit-currencies) 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**

> **Info**
>
> **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

| Field                          | Meaning                                            |
| ------------------------------ | -------------------------------------------------- |
| `available_balance`            | Credits ready to spend                             |
| `pending_balance`              | Credits from unpaid invoice (platform fee benefit) |
| `overage_used / overage_limit` | Optional credit line when prepaid is insufficient  |
| `conversion_rate`              | USD per credit for invoicing and reporting         |
| `rollover_enabled`             | Unused 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](/documentation/introduction/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

> **Warning**
>
> 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

| Field            | Meaning                                                    |
| ---------------- | ---------------------------------------------------------- |
| `postpaid_used`  | Credits accrued this billing period (resets after invoice) |
| `postpaid_limit` | Hard 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

| Type                  | Wallet   | Description                                    |
| --------------------- | -------- | ---------------------------------------------- |
| `CREDIT_BENEFIT`      | Prepaid  | Credits from platform fee (pending until paid) |
| `CREDIT_TOPUP_DIRECT` | Prepaid  | Manual 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 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.

* [Prepaid Wallets API](/api-reference/prepaid-wallets-api)
* [Postpaid Wallets API](/api-reference/postpaid-wallets-api)

---

## Related guides

* [Credit Currencies](/documentation/introduction/credit-currencies) — define currencies before wallets
* [Orders & Invoicing](/documentation/introduction/orders-and-invoicing) — activate billing for credit benefits
* [Plans](/documentation/introduction/plans) — bundle credits in plan platform fees