Skip to navigation

API Reference — Postpaid Wallets

Check accrued postpaid usage and report billable events. Endpoints live on the Control Plane API at https://cp-api.withpaygent.com and authenticate with your paygent-api-key header.

Prerequisites

Postpaid wallets are created in the dashboard only (Customer → Wallet → Postpaid). The agent indicator must use CREDITS billing with the same credit currency as the wallet. 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 postpaid accrual

GET /api/v1/wallet/balance returns all wallets for a customer. For postpaid wallets, use postpaid_used and postpaid_limit only—do not use available (it stays 0).

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

Example response (postpaid)

200 OK
{
  "balances": {
    "cx": {
      "available": 0,
      "pending": 0,
      "overage_used": 0,
      "overage_limit": 0,
      "postpaid_used": 30,
      "postpaid_limit": 0
    }
  }
}

Postpaid response fields

FieldDescription
postpaid_usedCredits accrued this billing period. Resets after invoice is generated.
postpaid_limitHard stop limit. 0 = no enforced limit.

Send usage (accrue postpaid)

POST /api/v2/usage reports usage and accrues credits on the postpaid wallet when the indicator is priced in CREDITS. Processing is async via Kafka; balance updates within a few seconds.

cURL
curl --location 'https://cp-api.withpaygent.com/api/v2/usage' \
--header 'accept: application/json' \
--header 'paygent-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "agentId": "postpaid_1",
  "customerId": "wallet-post-1",
  "indicator": "per_minute",
  "rawUsage": {
    "provider": "OPENAI",
    "model": "gpt-4o-mini",
    "plan": "default",
    "inputTokens": 120,
    "outputTokens": 80
  }
}'

Alternatively use the Python SDK: client.send_usage(agent_id, customer_id, indicator, usage_data). For local testing, set client.base_url to your Control Plane host.

Postpaid integration flow

  1. GET /api/v1/wallet/balance — read postpaid_used and postpaid_limit.
  2. If under the limit (or limit is 0), perform the LLM / API work.
  3. POST /api/v2/usage — accrue usage on the postpaid wallet.
  4. Customer is invoiced at period end; postpaid_used resets to 0.
Example (Python)
import requests
API_KEY = "YOUR_API_KEY"
BASE = "https://cp-api.withpaygent.com"
CUSTOMER = "wallet-post-1"
CURRENCY = "cx"
# 1. Check postpaid limit before usage
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, {})
used = state.get("postpaid_used", 0)
limit = state.get("postpaid_limit", 0)
if limit > 0 and used >= limit:
    raise Exception("Postpaid credit limit reached")
# 2. After successful work, send usage
# client.send_usage("postpaid_1", CUSTOMER, "per_minute", usage_data)
Not supported via API

Postpaid wallet creation and top-up are not available on the public API. Use the dashboard to create postpaid wallets.

Prepaid wallets: Prepaid Wallets API