API Authentication

All merchant OpenAPI requests to BizFlex Africa must be authenticated with your secret API key.

We use a header-based scheme so every call is attributed to the correct merchant and can be audited.

The `x-api-key` header

Send your secret API key in the x-api-key HTTP header on every protected request.

Keys are shown once when created (or reset) in the dashboard. Store them securely — BizFlex does not store the plaintext key for later retrieval.

Where to find your key

Sign in to the BizFlex Dashboard.
Open Settings → API Keys.
Create a key (or reset if allowed), then copy it immediately.

Environments and key prefixes

Environment	Typical base URL	Key prefix	Notes
Live		`bf_live_`	Production only. Merchant must be ACTIVE and go-live enabled.
Test		`bf_test_`	Not accepted on the live API.

Example key shapes (not real keys):

Live: bf_live_xK9m…
Test: bf_test_aB3c…

Using the wrong prefix for the environment returns 401.

Confirm the exact live and sandbox hosts with your BizFlex account manager or the Getting Started page if they differ from the table above.

Required headers

Header	Required	Value	Description
`x-api-key`	Yes	`bf_live_…` or `bf_test_…`	Your merchant secret key (including prefix).
`Content-Type`	POST / PUT / PATCH	`application/json`	JSON request body.
`Accept`	Recommended	`application/json`	Prefer JSON responses.

Transport

All API calls must use HTTPS (TLS).
Plain HTTP requests are rejected.

Merchant readiness checklist

Before live traffic will succeed, ensure:

Merchant profile is approved and business status is ACTIVE.
Go-live is enabled for production.
Your key status is ACTIVE (not revoked / inactive).
If you configured an IP allowlist, the calling server IP is included.
If you configured an origin allowlist, the request Origin / Referer / Host matches.

Tor / .onion traffic is not allowed.

Implementation examples

Merchant OpenAPI routes live under the /dev/... namespace (for example payouts and customers).

cURL — list / call a protected route

curl https://api.bizflex.africa/v1/dev/payouts \
  -H "x-api-key: $BIZFLEX_SECRET_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

cURL — create an NGN payout (illustrative)

curl https://api.bizflex.africa/v1/dev/payouts \
  -X POST \
  -H "x-api-key: $BIZFLEX_SECRET_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "walletId": "550e8400-e29b-41d4-a716-446655440000",
    "destinationBankCode": "058",
    "destinationAccountNumber": "0123456789",
    "destinationAccountName": "Ada Okeke",
    "amount": 10000,
    "remarks": "Vendor payment"
  }'

amount on payouts is in kobo (minor units of NGN). Example: 10000 = ₦100.00. See the Payouts reference for full field rules.

Node.js (Axios)

const axios = require('axios');

const client = axios.create({
  baseURL: process.env.BIZFLEX_API_BASE_URL, // e.g. https://api.bizflex.africa/v1
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    'x-api-key': process.env.BIZFLEX_SECRET_KEY, // bf_live_... or bf_test_...
  },
  timeout: 30000,
});

async function createPayout() {
  const { data } = await client.post('/dev/payouts', {
    walletId: '550e8400-e29b-41d4-a716-446655440000',
    destinationBankCode: '058',
    destinationAccountNumber: '0123456789',
    destinationAccountName: 'Ada Okeke',
    amount: 10000, // kobo
    remarks: 'Vendor payment',
  });
  console.log(data);
}

createPayout().catch((err) => {
  console.error(err.response?.data || err.message);
});

Error responses

Failed authentication returns 401 Unauthorized with a JSON body:

{
  "success": false,
  "message": "Invalid API Key",
  "data": null
}

Common auth failures

HTTP status	Example `message`	Typical cause
401	`API Key is required`	Missing `x-api-key` header
401	`Invalid API Key`	Unknown or mistyped key
401	`Invalid API key format`	Missing / wrong `bf_live_` or `bf_test_` prefix
401	`Test API keys are not valid in production`	`bf_test_` sent to live
401	`Live API keys are not valid in this environment`	`bf_live_` sent to sandbox
401	`API Key is inactive or revoked`	Key disabled
401	`Merchant is not live`	Go-live not enabled (production)
401	`Merchant is not active`	Merchant / business not ACTIVE
401	`IP address not allowed`	Caller IP not on allowlist
401	`Origin not allowed`	Origin / host not on allowlist
401	`API requests must use HTTPS (TLS)`	Request not over HTTPS
401	`Tor traffic is not allowed`	Tor exit / onion request

Most auth failures use 401. Treat any non-success: true response as failed and inspect message.

Security checklist

Store BIZFLEX_SECRET_KEY in server env / secrets manager — never in frontend, mobile apps, or public repos.
Call the merchant API only from your backend.
Use bf_test_ keys in sandbox and bf_live_ keys in production — never mix.
Prefer an IP allowlist for live keys.
If a key is exposed (e.g. committed to Git), rotate/reset immediately in the dashboard and revoke the old key.
Never log the full x-api-key value.
Always use HTTPS.

Example Response:

{
  "success": true,
  "message": "Transactions fetched successfully",
  "data": [
    { "id": 1, "amount": 1000 },
    { "id": 2, "amount": 500 }
  ],
  "meta": {
    "total_records": 150,
    "current_page": 1,
    "total_pages": 75,
    "per_page": 2
  }
}