Skip to main content
Finora Business
Finora Business
Sign InStart Free Trial

Reference

Enterprise Management

Enterprise only

Provision and deprovision businesses under an enterprise account, inspect API usage, and manage the shared wallet.

The enterprise management module is for bank partners and multi-tenant operators running many businesses under a single Finora Business enterprise account. It covers provisioning (creating a business + owner in one call), deprovisioning, usage reporting, and wallet management.

Authorization

Unlike business-scoped routes, enterprise endpoints do not verify businessId access. Instead, your API key's user must be listed in the enterprise's adminUserIds. Non-admins receive 403 FORBIDDEN.

List enterprise businesses

GET/v1/enterprise/businesses

Returns the businesses linked to your enterprise, newest first.

Query parameters

FieldTypeRequiredNotes
limitintegernoDefault 50, max 100.
offsetintegernoSkip N results.
statusstringnoactive, expired, or suspended.
searchstringnoSubstring match on business name.

Response — 200

{
  "success": true,
  "data": {
    "businesses": [
      {
        "id": "biz_001",
        "name": "Acme Suya Spot",
        "email": "ops@acme.ng",
        "industry": "Food & Beverage",
        "subscriptionTier": "enterprise",
        "enterpriseSubscriptionStatus": "active",
        "enterpriseSubscriptionExpiresAt": "2026-12-31T23:59:59.000Z",
        "setupComplete": true,
        "createdAt": "2026-01-15T09:00:00.000Z"
      }
    ],
    "pagination": { "total": 145, "limit": 50, "offset": 0, "hasMore": true }
  }
}

Provision a new business

POST/v1/enterprise/businesses

Creates a Firebase Auth user (or finds one by email), creates the business document with COA seeded, and links it to your enterprise.

Body

FieldTypeRequiredNotes
ownerEmailstringyesCreates a Firebase Auth user if none exists.
ownerFirstNamestringyes
ownerLastNamestringyes
ownerPhonestringno
businessobjectyesBusiness details — see below.
business.namestringyes
business.emailstringyes
business.industrystringyes
coaTemplatestringnoregular (default) or school.
subscriptionTypestringnomonthly (default) or annual.

Response — 201

{
  "success": true,
  "data": {
    "businessId": "biz_new123",
    "userId": "user_new456",
    "name": "Acme Retail Ltd",
    "subscriptionExpiresAt": "2026-05-17T23:59:59.000Z",
    "coaTemplate": "regular",
    "setupComplete": true
  }
}

Provisioned businesses skip the setup wizard (setupComplete: true) and come pre-seeded with the Nigerian chart of accounts.

Deprovision a business

DELETE/v1/enterprise/businesses/{businessId}

Unlinks the business from the enterprise. Does NOT delete data — the owner retains access independently.

After deprovisioning, the business's subscriptionTier drops to free and it is no longer billed against your enterprise wallet. Historical data stays intact for the business owner.

Usage report

GET/v1/enterprise/usage

Aggregate API usage across all businesses in the enterprise for a date range.

Query parameters

FieldTypeRequiredNotes
startDatestring (ISO)noDefaults to start of current month.
endDatestring (ISO)noDefaults to today.

Response — 200

Returns totalBusinesses, activeBusinesses, totalAPIRequests, a requestsByEndpoint breakdown, and a perBusiness array with per-tenant metrics. See the source file for the full shape.

Wallet balance

GET/v1/enterprise/wallet

Returns the enterprise wallet balance, lifetime topups and spend, and next billing date.

Response — 200

{
  "success": true,
  "data": {
    "balanceKobo": 5000000000,
    "balance": 50000000.00,
    "totalTopupsKobo": 10000000000,
    "totalSpentKobo": 5000000000,
    "businessCount": 145,
    "nextBillingDate": "2026-05-01T00:00:00.000Z"
  }
}

Top up the wallet

POST/v1/enterprise/wallet/topup

Records a wallet topup. Settlement happens out-of-band; the reference is for your reconciliation.

Body

FieldTypeRequiredNotes
amountnumberyesAmount in naira.
paymentMethodstringyese.g. bank_transfer.
referencestringyesYour unique reference for this topup.

403 response for retail keys

Calling any /v1/enterprise/* endpoint with a retail API key returns:

{
  "success": false,
  "error": {
    "code": "ENTERPRISE_ONLY",
    "message": "This endpoint requires an enterprise subscription. Contact sales at https://finorabusiness.com/contact",
    "requestId": "req_..."
  }
}

Ready to go enterprise?

Enterprise provisioning, shared wallets, and multi-tenant analytics are part of the enterprise tier. Contact sales to discuss pricing and partnership terms.

Related endpoints

Reference index

Back to all modules