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

# Your balance

> The prepaid wallet registrations are paid from: funding it, reading it, and its transactions.

Registrations are paid from your organization's prepaid wallet. Submit charges the price,
₦35,000, from it ([Submitting](https://docs.fastcac.com/guides/registrations.md#submitting)). You fund it by bank transfer.

Each mode has its own wallet. A test key reads and spends the test wallet, a live key the live one.

## Funding your wallet

Your organization gets its own funding account: a bank account number that credits your wallet.
Once it's active, it's on the **Billing** page at
[developers.fastcac.com](https://developers.fastcac.com) and in `funding_account` on
`GET /v1/balance`. Transfer to it from any Nigerian bank.

* **Deposits are credited in full.** FastCAC pays the bank-transfer fee, so ₦350,000 sent is
  ₦350,000 available.
* **A deposit doesn't submit anything.** It only adds to your balance; you call submit when you're
  ready.
* **Large deposits can be held.** A deposit that takes you over the daily deposit limit shows in
  `held`, not `available`, until it's released. FastCAC releases it into `available` once the
  bank transfer clears, which records a `deposit_released` transaction and sends `balance.funded`.
  If a deposit stays held, contact [fastcac@mydigitalabode.com](mailto:fastcac@mydigitalabode.com).
* You get [`balance.funded`](https://docs.fastcac.com/webhooks/events#wallet) when a deposit is credited to `available`.

In test mode the funding account is a fake one (`0000000000`, TEST BANK), and you add test money
with a [test helper](#test-mode) instead.

## Reading your balance

```bash theme={null}
curl https://api.fastcac.com/v1/balance \
  -H "Authorization: Bearer $FASTCAC_KEY"
```

```json Response (test key) theme={null}
{
  "object": "balance",
  "available": "1245000.00",
  "held": "0.00",
  "currency": "NGN",
  "low_balance_threshold": "100000.00",
  "funding_account": {
    "account_number": "0000000000",
    "bank_name": "TEST BANK",
    "account_name": "FastCAC - TEST MODE"
  }
}
```

| Field | Meaning |
| - | - |
| `available` | What submit can spend, in naira, as a decimal string. |
| `held` | Deposits received but not yet released, in naira. Not spendable. |
| `currency` | Always `NGN`. |
| `low_balance_threshold` | The threshold you set on the Billing page, in naira, or `null` if you haven't set one. See [Low balance](#low-balance). |
| `funding_account` | Where to send a transfer: `account_number`, `bank_name` and `account_name`. `null` in live mode until your funding account is active. |

## Transactions

Every change to the balance is a `wallet_transaction`. List them newest first; the list
[paginates](https://docs.fastcac.com/api-basics/pagination.md) with `limit` and `starting_after`.

```bash theme={null}
curl "https://api.fastcac.com/v1/balance/transactions?limit=3" \
  -H "Authorization: Bearer $FASTCAC_KEY"
```

```json Response (abridged) theme={null}
{
  "object": "list",
  "data": [
    {
      "object": "wallet_transaction",
      "id": "wtx_4BsHlzS5uvTnbVwSGJ7VkI",
      "type": "deposit",
      "amount": "350000.00",
      "balance_after": "1245000.00",
      "currency": "NGN",
      "registration_id": null,
      "sender_name": "TEST DEPOSIT",
      "sender_bank": null,
      "description": "Simulated bank transfer (test mode).",
      "created_at": "2026-10-25T03:34:03Z"
    },
    {
      "object": "wallet_transaction",
      "id": "wtx_2w2UDtdaNiFP1RSrug4ObA",
      "type": "registration_charge",
      "amount": "-35000.00",
      "balance_after": "895000.00",
      "currency": "NGN",
      "registration_id": "reg_2hVXkBBGA34cZB4cmO8oAu",
      "sender_name": null,
      "sender_bank": null,
      "description": "Business Name registration reg_2hVXkBBGA34cZB4cmO8oAu",
      "created_at": "2026-10-25T03:34:02Z"
    },
    ...
  ],
  "has_more": true
}
```

`amount` is signed: positive adds to the balance, negative takes from it. `balance_after` is the
available balance once it applied. Both are naira, as decimal strings.

| `type` | What it is |
| - | - |
| `deposit` | A bank transfer to your funding account, credited to `available`. `sender_name` and `sender_bank` say who sent it, where the bank tells us. |
| `deposit_held` | A large deposit, received but held. It counts toward `held`, not `available`, so `balance_after` doesn't change. |
| `deposit_released` | A held deposit was released into `available`. `amount` is the deposit's amount. |
| `registration_charge` | Submit charged a registration's price. `registration_id` names it. |
| `adjustment` | A correction FastCAC made to your live balance; `description` says why. |
| `test_credit` | The test money a new test wallet starts with. Test mode only. |

## Refunds

There are no refunds. Once submit charges a registration, the charge stands whatever CAC decides:
a rejected registration isn't refunded, and a new registration after a rejection is charged again.
Resubmitting after `verification_failed` or a query doesn't charge again. If FastCAC charged you by
mistake, it corrects it with an `adjustment`.

## Low balance

Set a low-balance threshold on the Billing page and FastCAC sends
[`balance.low`](https://docs.fastcac.com/webhooks/events#wallet) when a charge takes your balance from at or above it to
below it. It's sent once per crossing: further charges below the threshold don't send it again
until a deposit lifts the balance back up and a charge crosses it once more. Use it to top up
before a submit gets `402 insufficient_balance`
([Your wallet](https://docs.fastcac.com/guides/registrations.md#your-wallet)).

## Test mode

Each organization's test wallet starts with ₦1,000,000 of test money. Test submits really draw it
down, so after 28 registrations a submit gets a real `402` until you add more. (Pass
`?simulate=insufficient_balance` on submit to force the `402` at any time. That simulates an empty
wallet, so its `details.balance` is `0.00` whatever the test wallet holds.)

Add test money with the deposit helper, as if a bank transfer reached your funding account. It
credits the test wallet and sends `balance.funded`:

```bash theme={null}
curl -X POST https://api.fastcac.com/v1/test_helpers/deposits \
  -H "Authorization: Bearer $FASTCAC_KEY" -H "Content-Type: application/json" \
  -d '{"amount": "350000.00"}'
```

```json Response (201) theme={null}
{
  "object": "wallet_transaction",
  "id": "wtx_4BsHlzS5uvTnbVwSGJ7VkI",
  "type": "deposit",
  "amount": "350000.00",
  "balance_after": "1245000.00",
  "currency": "NGN",
  "registration_id": null,
  "sender_name": "TEST DEPOSIT",
  "sender_bank": null,
  "description": "Simulated bank transfer (test mode).",
  "created_at": "2026-10-25T03:34:03Z"
}
```

`amount` is naira as a decimal string, more than 0 and at most 10,000,000 (`400 parameter_invalid`
otherwise). With a live key the helper answers `403`:

```json 403 theme={null}
{
  "error": {
    "type": "permission_error",
    "code": "test_mode_only",
    "message": "Deposits can only be simulated with a test key.",
    "param": null,
    "request_id": "req_wEqbJcDg1QV2ed9VSXanC7HG"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.