Skip to navigation

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
{
  "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

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
{
  "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)
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