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.

Authentication

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

FieldDescription
availablePrepaid credits ready to spend.
pendingCredits from unpaid invoice benefits.
overage_used / overage_limitCredit 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
$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
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

  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)
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: Postpaid Wallets API