NorthPole — Business API

x-api-key authenticated endpoints

This page documents only the server-to-server endpoints secured by an x-api-key header. These endpoints are intended for backend integrations and require a business API key issued from the dashboard.

Authentication

All requests must send the header x-api-key: YOUR_BUSINESS_API_KEY. Unauthorized or missing keys return 401 Unauthorized.

GET /api/business/details
Headers:
  x-api-key: YOUR_BUSINESS_API_KEY

Business metadata

Retrieve public-facing business details (id, name, logo, KYB status, active flag).

GET /api/business/details
Headers:
  x-api-key: YOUR_BUSINESS_API_KEY

Response 200:
{
  "id": "business_123",
  "name": "Acme Corp",
  "logo": "https://.../logo.png",
  "kyb_status": "verified",
  "is_active": true
}

Wallets

List all wallets owned by the authenticated business, including associated virtual account details.

GET /api/business/wallets
Headers:
  x-api-key: YOUR_BUSINESS_API_KEY

Response 200: Array of wallets with currency, balance, and optional virtual_account

Payment sessions

Create and manage time-limited payment sessions that customers use to complete payments into your business virtual account.

Create a payment session

POST /api/business/payments/session
Headers:
  x-api-key: YOUR_BUSINESS_API_KEY
Content-Type: application/json

{
  "amount": 5000,
  "currency": "NGN",
  "customer_name": "John Doe",
  "customer_email": "john@example.com",
  "metadata": { "order_id": "ORD-1001" }
}

Get payment session details (public)

GET /api/business/payments/session/:sessionId
(public endpoint — does not require API key)

Verify a payment session

GET /api/business/payments/session/:sessionId/verify
Headers:
  x-api-key: YOUR_BUSINESS_API_KEY

List payment sessions for a business

GET /api/business/:businessId/payments/sessions
Headers:
  x-api-key: YOUR_BUSINESS_API_KEY

Errors and rate limits

Invalid or missing API keys return 401. Rate limits and quota exceeded return 429. All error responses follow the format {"success":false,"message":"..."} where possible.

Notes

Use your server backend to keep API keys secret — never embed them in client-side code.
Rotate API keys periodically and remove compromised keys from the dashboard.
Use business API endpoints for reconciliation, reporting, and creating payment sessions — interactive user auth uses bearer tokens and different endpoints.