Wallet balance

Returns your prepaid wallet balance — the funded NGN account used for gift-card purchases and other debits.

Postpaid customers do not use wallet balance. This endpoint applies to prepaid merchants only.


GET /v1/wallet/balance

Example


curl "https://api.breezeinnovations.io/v1/wallet/balance" \
  -H "X-Merchant-Key: mk_your_key_id" \
  -H "X-Merchant-Secret: your_issued_secret"

Sample response:


{
  "status": "success",
  "data": {
    "merchant_id": 42,
    "currency": "NGN",
    "balance": "125000.50",
    "billing_mode": "prepaid",
    "credit_floor": "0.00"
  },
  "total": "125000.50"
}

Field	Description
`data.balance` / `total`	Current available prepaid balance
`data.currency`	Wallet currency (typically `NGN`)

If no prepaid wallet is enrolled, the API returns 404 (merchant wallet not enrolled). Ask your account manager to enable prepaid wallet billing for your merchant.

Funding account (bank transfer)

When bank transfer funding is enabled for your merchant wallet currency, you can request a static bank account for wallet top-ups in that currency (NGN, USD, GBP, EUR, … — one account per currency). Transfers credit your prepaid wallet. NGN deposits deduct a flat ₦100 convenience fee; other currencies currently have no fee. If the endpoints return 403, ask your account manager to enable bank funding on the wallet for that currency.

Create / resume funding account


POST /v1/wallet/funding-account
Content-Type: multipart/form-data

Form fields:

Field	Required	Notes
`currency`	no	Defaults to `NGN`
`bvn`	for NGN	11 digits
`email`, `first_name`, `last_name`, `phone_number`	first time	Stored for retries / other providers
`date_of_birth`	no	`YYYY-MM-DD`
`id_card`	first time	JPEG, PNG, WebP, or PDF, max 5MB — stored in object storage

JSON without id_card is only accepted when an ID was already saved on a pending account.

Get funding account(s)


GET /v1/wallet/funding-account
GET /v1/wallet/funding-account?currency=NGN

Optional currency filters to one ISO code. Response includes account_number, account_name, bank_name, currency, status, and convenience_fee for the fee currency. Credits appear as ledger fund entries for the net amount (gross − fee when applicable).