# Top-ups and statements

> Live checks are paid from a prepaid naira wallet. Fund it by bank transfer to a one-time account, and download a monthly statement.

Every live check (verified or not-found) is charged to your workspace wallet at the price shown on the [pricing page](https://speedmap-delta.vercel.app/pricing). Sandbox checks, failed calls and idempotent retries are never charged. When the balance is lower than the price of a check, live requests fail with `402 insufficient_balance` until you top up.

## How a top-up works

Top-ups are bank transfers, collected by **FintavaPay**. Each top-up gets its own one-time virtual account, so your transfer is matched automatically and no reference number is needed.

### 1. Choose an amount

In **Billing → Top up**, enter any amount between ₦1,000 and ₦10,000,000. The first time, you also give a contact phone number, which the provider requires to open the account.

### 2. Transfer to the one-time account

The dashboard shows a bank, account number and account name. Send **exactly** the amount shown from any Nigerian bank app. The account is valid for a short window (shown as a countdown); it is for this top-up only and must not be reused.

### 3. The wallet is credited

The provider notifies Speedmap when the transfer lands, usually within a minute. The dashboard polls every 5 seconds, so you can watch it settle; **I’ve sent it** asks the provider directly if you are in a hurry. A receipt is emailed to billing recipients and the top-up appears in the ledger.

> **One open request at a time:** A workspace can have one pending top-up. Opening the dialog again shows the same account until it is paid or expires. If a request expires after you have already transferred, use **I already paid**: the transfer is still matched and credited.

## Payment statuses

| Status | Meaning |
| --- | --- |
| `pending` | Account open, waiting for the transfer. |
| `paid` | Transfer confirmed; the wallet was credited the amount the bank confirmed. |
| `expired` | The window closed before a transfer was confirmed. Start again for a new account. |
| `failed` | The provider could not open an account. Nothing was charged. |

The amount credited is always what the provider confirms was received, so a transfer that is short or over by a few naira is credited as received.

## Low-balance alerts

Owners and admins (configurable) are emailed once a day while the wallet is below the threshold set in **Settings → Notifications**, and again when it reaches ₦0. The dashboard sidebar shows the balance and a projected runway from your 30-day average.

## Monthly statements

On the 1st of each month, a statement for the previous month is generated with the opening and closing balance, top-ups, charges and a CSV of every ledger entry and billed check. It is emailed to billing recipients and listed under **Billing → Statements** for download. Statements never include identity data; checks are listed by `reference_id`, product and price.

## Local development

When the API runs with the simulated payment provider (`PAYMENT_PROVIDER=simulated`, the default), the dialog shows a clearly labelled **Simulate transfer** button that settles the top-up instantly. A real FintavaPay account is needed for live collection; the webhook is verified by signature and the wallet is only credited after a provider status check.

**Payment object**

```json
{
  "id": "pay_01hx3m9f8b2t",
  "object": "payment",
  "amount_kobo": 2000000,
  "status": "pending",
  "provider": "fintava",
  "account": {
    "number": "9012345678",
    "name": "SPEEDMAP / SKAIKRU LENDING",
    "bank": "Wema Bank"
  },
  "expires_at": "2026-10-20T10:42:00.000Z",
  "paid_at": null,
  "created_at": "2026-10-20T10:12:00.000Z"
}
```

---

Source: https://speedmap-delta.vercel.app/docs/topups