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
1{
2  "balances": {
3    "cx": {
4      "available": 0,
5      "pending": 0,
6      "overage_used": 0,
7      "overage_limit": 0,
8      "postpaid_used": 30,
9      "postpaid_limit": 0
10    }
11  }
12}

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)
1import requests
2
3API_KEY = "YOUR_API_KEY"
4BASE = "https://cp-api.withpaygent.com"
5CUSTOMER = "wallet-post-1"
6CURRENCY = "cx"
7
8# 1. Check postpaid limit before usage
9resp = requests.get(
10    f"{BASE}/api/v1/wallet/balance",
11    params={"customer_id": CUSTOMER},
12    headers={"paygent-api-key": API_KEY},
13)
14state = resp.json()["balances"].get(CURRENCY, {})
15used = state.get("postpaid_used", 0)
16limit = state.get("postpaid_limit", 0)
17if limit > 0 and used >= limit:
18    raise Exception("Postpaid credit limit reached")
19
20# 2. After successful work, send usage
21# 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