Wallet balance

GET /v1/wallet/balance

Returns your prepaid wallet balance — the funded NGN account used for airtime, data, and bill payments.

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

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

HTTP 200 — sample response:

{
  "state": "ok",
  "result": {
    "merchant_id": 42,
    "currency": "NGN",
    "balance": "125000.50",
    "billing_mode": "prepaid",
    "credit_floor": "0.00"
  }
}

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

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.

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

Create body: currency (defaults to NGN), bvn (required for NGN), plus email, first_name, last_name, phone_number on first registration (optional date_of_birth), and multipart field id_card (JPEG/PNG/WebP/PDF, max 5MB). Use multipart/form-data when uploading an ID. Later calls for the same merchant + currency return the existing account. Response includes account_number, account_name, bank_name, currency, status, id_document_uploaded, and convenience_fee.

MTN vending balance

GET /v1/wallet/mtn/balance

Separate from the prepaid wallet above. Returns your MTN vending balance.

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

HTTP 200 — sample response:

{
  "state": "ok",
  "result": {
    "wallets": [
      {
        "phone": "08030000000",
        "balance": "125000.50",
        "client_name": "YOUR-MERCHANT-MTN"
      }
    ],
    "total": "125000.50"
  }
}

If MTN vending is not enabled on your profile, this returns 200 with an empty wallets array and a total of 0.00 — use prepaid wallet balance instead.