API access and billing

Using the API can carry a per-call charge. The bank sets a tariff on your client, every chargeable call is recorded against it as it happens, and once a day the total for the day is debited from your designated fee account as a single transaction. Nothing is charged per call, and nothing is ever charged to a customer’s wallet.

The tariff

Your client carries a fee configuration with two parts:

• a default fee, charged on any call not listed individually, and
• endpoint fees, keyed by method and path, for example POST /api/legacy/provider/wallets/transactions/banktransfer.

A call is matched to an endpoint fee first by its exact method and path, then by prefix, so a key such as POST /api/legacy/provider/wallets/transactions/bill prices both …/bill/validate and …/bill/pay. If no key matches, the default fee applies; if there is no default, the call is free. A tariff with no configuration at all means your client is not billed.

The portal’s API access page shows the tariff as it stands: the default fee and the sorted list of endpoint fees, per client.

What counts as a chargeable call

Every request made with your client’s token that completes with an HTTP status below 400 is recorded with the fee that applied at that moment. Two consequences are worth knowing:

• A legacy endpoint answering a business refusal (0004, 0012, 0094…) does so with HTTP 200, so it counts. A 403 from the scope filter or a 429 from the rate limiter does not.
• The fee recorded is the one in force when the call was made. A tariff change later does not restate earlier usage.

The record is the request audit log, the same one the bank uses to answer a query about any call you made.

Cache your token

The token endpoint is itself a call. Fetching a token per request would be billed per request where your tariff has a default fee. See Authentication.

When the charge is taken

1. Days are cut on UTC midnight. The billing period is the UTC calendar day, not the Lagos day.
2. At 02:00 UTC a job bills the day that has just closed, for every client that had chargeable calls.
3. It posts one FEE transaction per client per day from your fee account, narrated API access fees <date>, with a reference of the form APIFEE-<client>-<period>. The per-call detail stays in the audit log; the statement gets the total.
4. The same night it re-attempts any earlier period that was refused, going back 30 days.

The run is safe to repeat: a period already billed is never charged twice.

The fee account

The account the charge is taken from is designated by the bank when your client is approved and is named on the API access page. It must be active and hold enough for the day’s total. When it does not, the period is recorded as outstanding: the amount stays owed, is shown on the portal, and is retried each night until it is collected or until the 30-day retry window passes, after which it becomes a conversation with your relationship manager rather than a retry.

Reason a charge is refused	Effect
No fee account configured	Calls are recorded but nothing is debited. The bank will configure one.
Fee account frozen, locked or closed	Period outstanding; retried nightly.
Not enough available balance	Period outstanding; retried nightly.

Reading the portal

The API access page answers three questions that are deliberately kept apart.

Section	What it is
Clients	Each client your organisation holds: its client_id, status, scopes, rate limits, IP allowlist, last use, fee account number and tariff. Never a secret.
Usage	Calls made over a window you pick (UTC days, at most six months back, inclusive end), and the fees recorded against them, per client.
Charges	Periods the bank has actually billed, newest first, each with its call count, amount, whether it was taken and when, or whether it is outstanding.

Recorded fees are not a bill

The Usage total is the sum of fees recorded per call. A charge exists only once the nightly job has taken it. A day’s usage normally appears before its charge does, and a tariff change, a refused run or a bank adjustment can make the two differ. Reconcile your statement against Charges, and use Usage to understand them.

Clients are issued and secrets rotated by the bank through its own approval process; the portal shows and never changes them.

In the portal

The API access page, for organisations that hold a client. The daily FEE line also appears in the Transactions register and on the fee account’s statement under Accounts.