> 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.

# API Reference — Prepaid Wallets

Check prepaid balances and top up credits programmatically. Endpoints live on the **Control Plane API** at `https://cp-api.withpaygent.com` and authenticate with your `paygent-api-key` header.

> **Prerequisites**
>
> **customer\_id** is the customer's *external ID*. The customer must already have a **prepaid** wallet for the credit currency. Create wallets in the dashboard or via an order with platform-fee credit benefits. See [Credits & Wallets](/documentation/introduction/credits-and-wallets).

## Authentication

**`Header`**

```bash title="Header"
paygent-api-key: YOUR_API_KEY
```

> **API key in header only**
>
> Pass `paygent-api-key` as an HTTP header, not as a query parameter.

---

## Get prepaid balance

`GET /api/v1/wallet/balance` returns all wallets for a customer. For prepaid wallets, use `available`, `pending`, and overage fields.

**`cURL`**

```bash title="cURL"
curl --location 'https://cp-api.withpaygent.com/api/v1/wallet/balance?customer_id=wallet-cust-7' \
--header 'accept: application/json' \
--header 'paygent-api-key: YOUR_API_KEY'
```

### Example response (prepaid)

**`200 OK`**

```json title="200 OK"
{
  "balances": {
    "Credits": {
      "available": 9500,
      "pending": 500,
      "overage_used": 0,
      "overage_limit": 1000,
      "postpaid_used": 0,
      "postpaid_limit": 0
    }
  }
}
```

For prepaid, check `available` before allowing usage. Ignore `postpaid_used` / `postpaid_limit` (they stay 0 on prepaid wallets).

### Prepaid response fields

| Field                            | Description                                            |
| -------------------------------- | ------------------------------------------------------ |
| `available`                      | Prepaid credits ready to spend.                        |
| `pending`                        | Credits from unpaid invoice benefits.                  |
| `overage_used` / `overage_limit` | Credit line used when prepaid balance is insufficient. |

---

## Top up prepaid wallet

`POST /api/v1/wallet/top-up` adds credits to a prepaid wallet. Overage is cleared first; the remainder goes to `available`.

**`cURL`**

```bash title="cURL"
curl --location 'https://cp-api.withpaygent.com/api/v1/wallet/top-up' \
--header 'accept: application/json' \
--header 'paygent-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "customer_id": "wallet-cust-7",
  "top_ups": [
    { "credit_currency_key": "Credits", "credits": 1000 }
  ]
}'
```

### Example response

**`200 OK`**

```json title="200 OK"
{
  "message": "Top-up successful",
  "results": [
    {
      "credit_currency_key": "Credits",
      "success": true,
      "available": 10500,
      "pending": 500
    }
  ]
}
```

---

## Prepaid integration flow

1. `GET /api/v1/wallet/balance` — check `available` (and overage if enabled).
2. If sufficient balance, perform the LLM / API work.
3. `POST /api/v2/usage` — report usage; credits are debited from prepaid balance.

**`Example (Python)`**

```python title="Example (Python)"
import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://cp-api.withpaygent.com"
CUSTOMER = "wallet-cust-7"
CURRENCY = "Credits"

resp = requests.get(
    f"{BASE}/api/v1/wallet/balance",
    params={"customer_id": CUSTOMER},
    headers={"paygent-api-key": API_KEY},
)
state = resp.json()["balances"].get(CURRENCY, {})
available = state.get("available", 0)
if available <= 0:
    raise Exception("Insufficient prepaid credits")

# After successful work: client.send_usage("agent_id", CUSTOMER, "indicator", usage_data)
```

---

Postpaid wallets: [Postpaid Wallets API](/api-reference/postpaid-wallets-api)