Skip to main content
Billing and reconciliation

Billing, credits and usage API

Read your own balance, holds, transactions and account-specific prices without exposing another tenant's commercial records.

Except for the public price catalogue, these endpoints require an authenticated Developer, Business, Partner or Reseller JWT. The server derives the tenant from the session—never from a caller-supplied account id.

Public catalogue and account-specific quote

GET/v1/pricing

The public catalogue returns active product prices, credit conversion and available payment methods. Its ETag is the catalogue version. Use it for published list prices, not for a customer's negotiated entitlement.

POST/v1/me/billing/quote

Quote the exact checks, optional country/document and optional project_id. A supplied project must belong to the caller. The response contains credits, usd, mode, itemized lines, bundled, billing_trigger and charge_sentence.

account-quote.sh
curl -X POST https://api.okias.io/v1/me/billing/quote \
  -H "Authorization: Bearer $DASHBOARD_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "checks": ["FULL_KYC"], "country": "pk", "doc_type": "NATIONAL_ID" }'
Do not invent a price
Unknown or unsellable checks return 400 VALIDATION_ERROR. A contract rate applies only where the billing engine has an active signed entitlement; a quote response is not itself a charge.

Credits and ledger

GET/v1/credits/balance
200 OK — synthetic balance example
{
  "balance": 1500,
  "held": 15,
  "available": 1485
}

balance is the credit wallet total, held is reserved for open operations and available is what can be spent. The actual response may include additional locked/allocation fields; clients must not discard them when reconciling.

GET/v1/credits/ledger

Returns the caller's credit-ledger history. Use its immutable entry ids and reasons for reconciliation; a balance response is not a substitute for the ledger.

Wallet and transaction history

GET/v1/me/billing/wallet
GET/v1/me/billing/transactions
GET/v1/me/billing/transactions/:id
GET/v1/me/billing/transactions.csv
Endpoint, Behavior
EndpointBehavior
walletCurrent account billing/wallet state.
transactionsTenant-scoped transaction history with the supported filters returned by the billing read model.
transactions/:idOne owned transaction; another tenant's id receives not-found behavior.
transactions.csvA no-store CSV export of the same authorized history; limited to ten requests per minute.

Account verification allocation

GET/v1/me/billing/credit-split
GET/v1/me/billing/credit-split/preview?purchased=1000&bonus=0
POST/v1/me/billing/credit-split/check
POST/v1/me/billing/credit-split/nominate
POST/v1/me/billing/credit-split/self-verification

These endpoints expose the current account's 10% available / 90% verification-linked allocation where that policy applies. Preview accepts positive integer purchased and optional non-negative integer bonus. Nomination body is { "verification_id": "…" }. Self-verification accepts no verification id: the server always uses the signed-in account.

Operation, Limit / safety
OperationLimit / safety
Split checkTen requests per minute; re-evaluates the caller's own allocation without providing a universal spending bypass.
Nomination and self-verificationFive requests per minute; ownership and eligibility are revalidated, and self-verification does not create a merchant charge.

Reseller usage and financial reporting

GET/v1/partners/clients/:accountId/usage
GET/v1/partners/financials

Reseller customer usage includes approved Live costs, matching reseller debits and permitted margin estimates. Financial reporting separates credits, commissions, reversals, pending payouts and available earnings. These are tenant-scoped reports, not proof of customer collection or an automatic payout instruction. See Reseller financial reporting.

Reconciliation rules

Status polling and page refreshes do not create charges. Verification creation uses an Idempotency-Key; worker retries and provider callbacks cannot create duplicate ledger entries. OTP products expose their own accepted-send charge and wallet-meter fields. Never infer a successful payment or verification solely from an HTTP retry.

Next steps