# Credits and payments

> Read your balances, add USD by card, set up auto top-up and spending limits, and see how funds are held while requests run.

Source: https://0.0.0.0:3000/docs/account/credits
Documentation index: https://0.0.0.0:3000/docs/llms.txt

Requests are paid from a prepaid balance. Each currency has its own balance: USD, funded by card, and BTC, funded with Bitcoin. This page covers USD funding, auto top-up, spending limits and reservations. For Bitcoin, see [Bitcoin payments](/docs/account/bitcoin).

## Balances

Open [Billing](/dashboard/billing). **Balances** shows one row per currency:

| Figure | Meaning |
| --- | --- |
| **Balance** | Credits minus charges, to the exact decimal |
| **Reserved** | Funds held for requests that are still running |
| **Available** | Balance minus reserved. This is what new requests can use |

USD and BTC balances are never added together, converted or used as a fallback for each other. A request draws only on the balance of its key's [currency](/docs/account/api-keys#the-billing-currency-is-permanent).

A row that reads **Empty — requests are paused until you add funds** has nothing available. **Paused for new top-ups and requests** means the currency is disabled for this account.

To read balances from code, call [`GET /credits`](/docs/account/management-keys#read-balances) with a management key. Per-key spend is in [`GET /key`](/docs/account/api-keys#inspect-the-current-key) and per-request cost in [`GET /generation`](/docs/account/usage-accounting#look-up-a-generation).

## Add USD credits by card

:::steps
### Open Add credits

In [Billing](/dashboard/billing), choose **Add credits** on the **US dollars** row.

### Choose an amount

Enter an exact amount or pick a preset (**$10**, **$25**, **$50** or **$100**). If the total payment, including the platform fee, falls outside the card limits, the dialog shows the minimum or maximum under the amount before you pay.

By default, the card platform fee is **5.5% of credits purchased, with a $0.80 minimum**: $5 in credits costs $5.80, and $100 costs $105.50. This is the total fee added to your purchase; payment processing costs aren't added separately. [Bitcoin top-ups](/docs/account/bitcoin) have a separate **5% fee with no minimum** by default.

### Pay

Your most recent saved card is preselected, or enter another in the secure card form. Card details go directly to the payment processor and never reach Numes. A new card is saved for later top-ups and auto top-up.

Before you confirm, the dialog shows **Credits purchased**, **Platform fee** and **Total payment**. The full credit amount goes to your balance; the platform fee is charged on top. If the fee changes before you pay, the dialog shows the new total and asks you to confirm again.

### Wait for confirmation

Credits post once the payment processor confirms the payment, not when your browser shows success. The top-up then reads **Credited** in **Funding history**.
:::

### Receipts

Every entry in **Funding history** opens a receipt with **Credit to balance**, **Platform fee**, **Charged to card**, the status and a reference for support. Other owners and administrators of the account can open the same receipt link.

| Status | Meaning |
| --- | --- |
| **Starting** | The payment is being created |
| **Needs a card** | Waiting for card details |
| **Needs confirmation** | Waiting for you to confirm the charge |
| **Needs action** | Your bank requires verification, such as 3-D Secure |
| **Processing** | Credits post once the payment is confirmed |
| **Credited** | The credit is in your balance |
| **Failed** | The charge didn't go through; nothing was credited |
| **Cancelled** | Cancelled before any charge |
| **Needs review** | The outcome is being checked; don't pay again |

If a top-up is waiting for you (a card, a confirmation or your bank's verification), continue it from its receipt rather than starting a new one.

Credits our team adds for a promotion or as compensation appear in **Funding history** as **Platform credit grant**. They're available immediately, pay only for USD keys, and can't be refunded.

If a card payment is declined, its receipt stays **Failed**, with no credits added. Start a new top-up to try another card.

### Saved cards

**Payment methods** lists your saved cards. Choose **Remove** to stop a card being charged. If auto top-up uses that card, it pauses until you choose another.

## Auto top-up

Auto top-up charges a saved card when the USD available balance drops to a threshold, so long-running workloads don't stop.

In **Auto top-up**, choose **Turn on auto top-up** (or **Change auto top-up**). You need at least one saved card. The dialog restates your rule in one sentence and shows what you pay per top-up. Set:

| Setting | Meaning |
| --- | --- |
| **When balance drops to** | Top up when available funds are at or below this amount |
| **Add credits of** | Credit added per top-up. Same limits and fee as a manual top-up |
| **Set a monthly cap** | Optional. Caps the total charged each UTC month, including fees. The dialog shows how many top-ups fit |
| **Charge to** | The saved card to charge |

How it behaves:

- **In the background.** Requests never wait for a top-up. A request that arrives while available funds are too low fails with `402`, even if a top-up is running.
- **Cooldown.** After a top-up, the next one waits at least an hour.
- **Monthly cap.** Pending and processing top-ups count toward the cap; failed or cancelled ones don't. A top-up that would exceed the cap waits until the next UTC month; its amount is never reduced to fit.
- **Fee changes.** Saving accepts the current platform fee. If the fee goes up, auto top-up pauses with **Review fee** until you choose **Accept fee and resume**.
- **Bank verification.** An unattended charge can't complete 3-D Secure. Auto top-up shows **Needs attention** until you confirm the charge from its receipt, change the card or change the settings.
- **Failures.** A declined charge is retried after the cooldown. After repeated failures, auto top-up turns itself off.

The panel shows **On**, **Off**, **Review fee**, **Needs attention** or **Failed**, with your threshold, amount, monthly cap, accepted fee and card. To stop, choose **Change auto top-up**, then **Turn off**.

## Spending limits

**Spending limit** in Billing caps what the whole account can spend in one currency across all keys. Choose the currency, then **Set a limit** (or **Change limit**), enter an exact amount, and choose when it **Resets**: **Daily**, **Weekly** or **Monthly**. Leave the amount empty for no limit.

- Periods start at 00:00 UTC each day, each Monday, or on the first of the month.
- The limit counts settled spend plus funds held for running requests. Once it's reached, new requests fail with `402` `insufficient_credits`.
- Each currency has its own limit. [Per-key limits](/docs/account/api-keys#spending-limits) apply as well.

## Reservations

Before a request runs, an upper bound of its cost is held against your balance and limits. When it completes, only the actual charge is taken and the rest is released. This is how a request never runs without the funds to pay for it.

For token-priced models, the hold is based on the model's full context and output limits, not on your prompt size or `max_tokens`. A short request can therefore need noticeably more available credit than it eventually costs, and running requests reduce **Available** until they finish.

See [Usage accounting](/docs/account/usage-accounting) for how the final charge is calculated.

## When funds run out

A request whose upper bound can't be held is rejected before it runs, and nothing is charged:

```json title="402 Payment Required"
{
  "error": {
    "code": 402,
    "message": "insufficient credits",
    "metadata": { "error_type": "insufficient_credits" }
  }
}
```

The same response is returned when a key or account spending limit stops the request. To find out which, check **Available** and **Spending limit** in [Billing](/dashboard/billing), and `limit_remaining` from [`GET /key`](/docs/account/api-keys#inspect-the-current-key). Then add credits, raise the limit or wait for running requests to finish. Don't retry a `402` in a loop.

## Refunds and disputes

There's no self-service refund. To ask for a refund of unused card credits, contact [Support](/dashboard/support) with the receipt reference within 24 hours of the purchase. Bitcoin payments and platform fees aren't refundable. The [Refund Policy](/legal/refunds) has the full rules.

Refunds and disputes may reverse credits. An account with a negative balance can't make requests in that currency until it's settled.

## Organizations

In an organization, only **owners** and **administrators** can add credits, manage saved cards, configure auto top-up and set spending limits. Every key in the organization shares the balance. See [Organizations](/docs/account/organizations).

## Next steps

:::cards
- {bitcoin} [Bitcoin payments](/docs/account/bitcoin) Fund a separate BTC balance over Lightning or on-chain.
- {receipt} [Usage accounting](/docs/account/usage-accounting) How each request is measured and charged.
- {key} [API keys](/docs/account/api-keys) Per-key spending limits and billing currency.
- {activity} [Activity and logs](/docs/account/activity) Where your spend goes.
:::