Billing

The KYC platform offers two billing rails. Tenants pick one when activating live mode — you can switch later from the portal.

Test mode is free

Test API keys (ak_test_...) are free and unlimited. They return deterministic results so you can exercise every branch of your integration without spending money.

Everything in live mode returns real results, is subject to rate limits tied to your plan, and consumes credits.

Fiat plans (Stripe)

Subscriptions billed monthly in USD. Unused verifications do not roll over.

The authoritative numbers live in the billing_plans table. The portal and the public GET /v1/billing/plans endpoint pull from the same row, so an admin price change takes effect everywhere without a redeploy.

Upgrades mid-cycle are prorated by Stripe; downgrades take effect at the next cycle.

USDT prepaid wallet (AIO v2)

For tenants that prefer stablecoin payments, the platform exposes a prepaid wallet topped up with USDT on Tron at the launch rate of $1.40 per verification. (Other chains will land post-launch.)

• Top up from the portal — pick a preset amount and we open a long-term pay-in window with AIO V2.
• Funds clear as soon as the AIO callback confirms the deposit on-chain.
• Balance is debited on successful verification only. failed, canceled, and expired verifications are not billed.
• Low-balance and depleted warnings fire as billing.balance.low and billing.balance.depleted webhooks once per crossing.

Read-only billing endpoints

Tenants can query billing state via the public REST API using a live API key. The portal hits the same surface under the cookie-authenticated /internal/portal/billing/* mirror.

• GET /v1/billing/plans — list active fiat plans + the prepaid rate (no auth).
• GET /v1/billing/subscription — the tenant's active subscription summary, or null for wallet-only tenants.
• GET /v1/billing/wallet — the tenant's prepaid wallet balance and per-session rate.
• GET /v1/billing/usage — current period usage rollup (anchored to the Stripe period for fiat plans, calendar month for wallet-only).

Mutations (start a Stripe checkout session, open a USDT top-up window, change plan) are portal-only and not part of the public REST contract.

Activating live mode

1. From the portal, go to Billing.
2. Either subscribe to a fiat plan via Stripe Checkout, or top up the USDT wallet with at least one week of expected volume.
3. Live mode flips on automatically once the Stripe webhook confirms the subscription, or once the AIO callback confirms the first top-up.
4. Issue a live key from API Keys → Create API key (live mode).

Live API keys are blocked at session creation time if the tenant has no active subscription and an empty wallet, so a misconfigured deploy fails closed rather than racking up unbilled volume.