> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pruva.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallet and billing

> When a check is charged, when it is not, and how pricing works.

Pruva runs on a prepaid wallet. Each live check debits your wallet at the scope's price. Test checks are never charged. The rules for what gets billed are simple once you know the one principle behind them.

## You are charged for an answer, not for a match

This is the whole model in one line. A provider bills Pruva the moment we call them, whether the record turns out to exist or not, so we bill you the same way.

| Outcome     | Charged? | Why                                                                                                  |
| ----------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `found`     | Yes      | The record exists. A real answer.                                                                    |
| `not_found` | Yes      | The record does not exist. Still a real answer the provider gave.                                    |
| `failed`    | No       | A timeout or outage. Not an answer about the subject, and something we did not pay the provider for. |

<Warning>
  The common mistake is to assume `not_found` is free. It is not. "This NIN does not exist" is a genuine result the provider charged us for, so it is charged to you. Only `failed`, where no answer was produced, is free.
</Warning>

## Found and not-found can be priced differently

A scope can carry two prices: one for a match, one for a no-match. Providers often charge less for a no-match, and that saving is passed through. The `priceKobo` on each result tells you exactly what that check cost.

Because the two can differ, Pruva checks your wallet against the **higher** of the two before running the check. If your balance cannot cover the worst case, the check is refused with `402` and nothing is spent, rather than calling the provider and discovering afterwards that you could not pay.

## Some scopes are priced per item

Most scopes cost one unit per call. A few are priced per item returned. Face detection is the clearest example: one call can return several faces, and it is priced per face. When this applies, `priceKobo` reflects the total for that call, and a call that returns nothing still bills once, because the provider was still called.

## When the wallet runs low

By default, a check is refused when your wallet cannot cover it, and your organization can be set to suspend at a zero balance. You can:

* Watch the balance in the dashboard, and set a **low balance alert** so you top up before checks start being refused.
* Ask support about **arrears**, allowing a trusted organization to run into a negative balance rather than be blocked. This is granted per organization, not by default.

<Note>
  A refused check for insufficient funds returns `402` with the reference, the price it would have cost, and your current balance, so you know exactly how much to add.
</Note>

## Amounts are in kobo

Every amount in the API, `priceKobo` and wallet balances alike, is in **kobo**, the minor unit of the naira. `5000` is ₦50.00. Keep amounts in the minor unit in your own code and divide by 100 only when you display them, to avoid rounding errors.

## Reading the cost of a check

The two fields to look at on any result:

* `priceKobo`, what the check cost.
* `charged`, whether your wallet was actually debited. A `found` or `not_found` result is normally `charged: true`; a `failed` result is always `charged: false`.

Reconcile against `charged`, not against `status` alone, so a rare case such as a result produced but not billable never over counts your spend.