API Billing Reconciliation Documentation

Security boundary

PayAPIKey's hosted endpoints do not accept gateway administrator tokens, channel keys, cookies, or sessions. Native API reads must happen in a local connector/sidecar you control; the hosted service receives stripped billing metadata only.

How it works

Read locally

A connector or sidecar you control uses administrator credentials to read the gateway's native API.

Strip and normalize

Remove keys, cookies, sessions, prompts, and completion content locally; submit billing metadata only.

Reconcile statelessly

Hosted endpoints return normalized data or a findings report immediately and do not provide credential storage.

Keep the three ledgers separate

A top-up is not consumption revenue. The engine treats the following as separate facts so cash collection is not mistaken for delivered-service revenue.

Downstream consumption

Customer request, model, channel, charged amount, refund, and price snapshot; revenue is recognized when usage is consumed.

Upstream delivery cost

Upstream request ID, actual cost, and refund; matched to downstream usage by requestId to calculate gross profit.

Payments and wallet funding

Captures, fees, refunds, chargebacks, and wallet credits; used to reconcile funding, not added to consumption revenue.

Start with two commands

Fetch the complete example, then submit its data object to the reconciliation endpoint. The example contains no real credentials or business data.

Shell

curl -s https://www.payapikey.com/api/v1/examples/reconciliation \
  | jq '.data' > reconciliation.json

curl -s -X POST https://www.payapikey.com/api/v1/reconcile \
  -H 'Content-Type: application/json' \
  --data-binary @reconciliation.json | jq

Each JSON request is limited to 2 MB and each ledger to 5,000 records. Batch by settlement period in production.