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 .

Authentication

Header

1paygent-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

1curl --location 'https://cp-api.withpaygent.com/api/v1/wallet/balance?customer_id=wallet-cust-7' \
2--header 'accept: application/json' \
3--header 'paygent-api-key: YOUR_API_KEY'

Example response (prepaid)

200 OK

1{
2  "balances": {
3    "Credits": {
4      "available": 9500,
5      "pending": 500,
6      "overage_used": 0,
7      "overage_limit": 1000,
8      "postpaid_used": 0,
9      "postpaid_limit": 0
10    }
11  }
12}

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

1curl --location 'https://cp-api.withpaygent.com/api/v1/wallet/top-up' \
2--header 'accept: application/json' \
3--header 'paygent-api-key: YOUR_API_KEY' \
4--header 'Content-Type: application/json' \
5--data '{
6  "customer_id": "wallet-cust-7",
7  "top_ups": [
8    { "credit_currency_key": "Credits", "credits": 1000 }
9  ]
10}'

Example response

200 OK

1{
2  "message": "Top-up successful",
3  "results": [
4    {
5      "credit_currency_key": "Credits",
6      "success": true,
7      "available": 10500,
8      "pending": 500
9    }
10  ]
11}

Prepaid integration flow

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

Example (Python)

1import requests
2
3API_KEY = "YOUR_API_KEY"
4BASE = "https://cp-api.withpaygent.com"
5CUSTOMER = "wallet-cust-7"
6CURRENCY = "Credits"
7
8resp = requests.get(
9    f"{BASE}/api/v1/wallet/balance",
10    params={"customer_id": CUSTOMER},
11    headers={"paygent-api-key": API_KEY},
12)
13state = resp.json()["balances"].get(CURRENCY, {})
14available = state.get("available", 0)
15if available <= 0:
16    raise Exception("Insufficient prepaid credits")
17
18# After successful work: client.send_usage("agent_id", CUSTOMER, "indicator", usage_data)

Postpaid wallets:

Need help? Contact us at support@withpaygent.com