Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.onecluster.co/llms.txt

Use this file to discover all available pages before exploring further.

​
How Billing Works

UBN BaaS uses a prepaid pay-as-you-go billing model. Every partner has a wallet that must have sufficient balance before making API calls. There are no monthly subscriptions, no credit terms, and no post-pay invoices.
Your wallet is automatically created when your go-live request is approved. You do not need to create it manually.

​
The Billing Cycle

1

Fund your wallet

Transfer money to your dedicated Virtual Account (VA) at Union Bank. The VA number is displayed on your Partner Dashboard. The transferred amount is instantly credited to your wallet balance.
2

Make API calls

Every billable API call checks your wallet balance. If you have sufficient funds, the call proceeds. If not, you receive a 402 Payment Required error and the call is blocked.
3

Automatic billing

When an API call is made, the cost is placed as a hold (lien) on your wallet. After the call completes successfully, the hold is converted to a permanent charge. If the call fails, the hold is released and your balance is restored.

​
Lien-Capture-Release

Every billable API call follows this pattern:
PhaseWhat happensYour balance
Lien (Hold)The cost of the API call is reserved from your available balanceAvailable balance decreases
Capture (Charge)The API call succeeded — the hold becomes a permanent chargeBalance decreases permanently
Release (Refund)The API call failed — the hold is releasedAvailable balance is restored
If an API call times out (status unknown), the hold remains active for up to 24 hours. If the status is still unknown after 24 hours, the hold is automatically released and your balance is restored.

​
Balance Fields

Your wallet has three balance fields:
FieldMeaning
BalanceTotal credits minus total charges — your overall API credit
Liened AmountSum of all active holds (in-flight API calls)
Available BalanceBalance - Liened Amount — what you can spend on new API calls

​
Pricing

API calls are billed at a flat rate per product:
API ProductPrice per Call (NGN)
Accounts10.00
Payments25.00
Collections15.00
KYC50.00
Prices shown are indicative and may change. Current prices are always available on your Partner Dashboard under Billing > Pricing.

​
Wallet Statement

Your wallet statement records every transaction:
TypeDescription
CreditWallet funding from your VA payment
HoldAPI call lien placed (in-flight)
DebitAPI call charged (call succeeded)
ReleaseAPI call refunded (call failed or timed out)
Each statement entry includes:
  • Date and time
  • Transaction type
  • The API endpoint that was called (for API charges)
  • Amount
  • Running balance
View your statement on the Partner Dashboard under Billing > Statement.

​
Insufficient Balance

If your available balance is less than the cost of an API call, the request is rejected with: 
{
  "success": false,
  "responseCode": "E402",
  "message": "Insufficient wallet balance",
  "data": {
    "requiredAmount": 25.00,
    "availableBalance": 10.00
  }
}
The API call is NOT forwarded to the downstream service. No action is taken. Fund your wallet and retry.

​
Wallet Lifecycle

StatusMeaningCan make API calls?Can receive funding?
ActiveNormal operating stateYesYes
SuspendedAdmin-initiated temporary blockNoYes
ClosedPermanently deactivatedNoNo
If your wallet is suspended, you can still fund it via your VA. Once unsuspended, your accumulated balance is available for API calls immediately.