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
/v1/pricingThe 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.
/v1/me/billing/quoteQuote 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.
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" }'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
/v1/credits/balance{
"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.
/v1/credits/ledgerReturns 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
/v1/me/billing/wallet/v1/me/billing/transactions/v1/me/billing/transactions/:id/v1/me/billing/transactions.csv| Endpoint | Behavior |
|---|---|
| wallet | Current account billing/wallet state. |
| transactions | Tenant-scoped transaction history with the supported filters returned by the billing read model. |
| transactions/:id | One owned transaction; another tenant's id receives not-found behavior. |
| transactions.csv | A no-store CSV export of the same authorized history; limited to ten requests per minute. |
Account verification allocation
/v1/me/billing/credit-split/v1/me/billing/credit-split/preview?purchased=1000&bonus=0/v1/me/billing/credit-split/check/v1/me/billing/credit-split/nominate/v1/me/billing/credit-split/self-verificationThese 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 |
|---|---|
| Split check | Ten requests per minute; re-evaluates the caller's own allocation without providing a universal spending bypass. |
| Nomination and self-verification | Five requests per minute; ownership and eligibility are revalidated, and self-verification does not create a merchant charge. |
Reseller usage and financial reporting
/v1/partners/clients/:accountId/usage/v1/partners/financialsReseller 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.