Developer docs

Getting started

Overview

NorthPole gives your business a REST API for accepting payments by bank transfer, managing virtual accounts, paying out to bank accounts, issuing virtual cards, and receiving real-time webhook notifications.

Base URL

https://api.northpoletradelink.com

What these docs cover

Every endpoint documented here is part of the API-key surface — the endpoints your server is allowed to call. NorthPole's own apps use separate session-authenticated routes that are internal, unsupported for third-party use, and deliberately not documented.

Core concepts

Concepts

Field	Type	Description
`Business`	object	Your company or organisation registered on NorthPole.
`API key`	credential	Authenticates your server's requests. Issuing one requires completed KYB verification.
`Wallet`	object	Holds your business balance in a specific currency (NGN, USD).
`Virtual account`	object	A bank account linked to your wallet for receiving transfers. Credits arrive automatically.
`Payment session`	object	A time-bound checkout for one customer and amount. Expires after 1 hour.
`Webhook`	callback	A signed HTTP callback NorthPole sends to your server when an event occurs.

Authentication

Every request carries your API key in the x-api-key header. A missing key returns 401 API key required; a key that does not resolve returns 401 Invalid API key.

Authenticated request

curl https://api.northpoletradelink.com/api/business/details \  -H "x-api-key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Modes

Each key belongs to one mode. The mode is encoded in the key prefix, so you can always tell which environment a key touches.

Key prefixes

Field	Type	Description
`pk_test_ / sk_test_`	test	Sandbox. Test-mode payment sessions can be settled by simulation without moving real money.
`pk_live_ / sk_live_`	live	Production. Required for payouts — a test key is rejected on the payout endpoint.

Keep keys server-side

An API key grants access to your business account and its balance. Store it in an environment variable or secrets manager, never in client-side code, a mobile bundle, or version control.

KYB verification

Before you can generate an API key or accept live payments, your business must complete Know Your Business verification. Submit your documents from the dashboard; once kyb_status is verified, the API becomes available.

Registered businesses submit registration details and upload CAC and MEMART documents.
Unregistered businesses can begin KYB without CAC or MEMART uploads.

Attempting this too early

Calling a key-issuing endpoint before verification completes returns 400 KYB_VERIFICATION_REQUIRED. Subscribe to the kyb.verified webhook to know the moment it clears.

Managing keys and webhooks

Keys and webhook endpoints are managed from the dashboard by the business owner, not with an API key — a key cannot mint or escalate another key. These routes are owner-authenticated, and are listed here because they are how you obtain the credential the rest of these docs assume.

API keys

POST/business/:id/api-keysOwner

GET/business/:id/api-keysOwner

DELETE/business/:id/api-keys/:keyIdOwner

POST/business/:id/api-keys/:keyId/rotateOwner

POST/business/:id/api-keys/:keyId/reveal-secretOwner

GET/business/:id/api-keys/usageOwner

POST /business/:id/api-keys · Response

{  "success": true,  "data": {    "key_id": "key_abc123",    "public_key": "pk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",    "secret_key": "sk_live_x9y8z7w6v5u4t3s2r1q0p9o8n7m6l5k4",    "api_mode": "live"  }}

Revealing a secret needs your password

The secret key is shown once at creation. Retrieving it later requires the account password via reveal-secret. Rotating a key replaces the secret and invalidates the previous one.

Webhook endpoints

POST/business/:id/webhooksOwner

GET/business/:id/webhooksOwner

PUT/business/:id/webhooks/:webhookIdOwner

DELETE/business/:id/webhooks/:webhookIdOwner

POST/business/:id/webhooks/:webhookId/enableOwner

POST/business/:id/webhooks/:webhookId/disableOwner

POST/business/:id/webhooks/:webhookId/testOwner

Quickstart

The shortest path to a completed payment: create a session, send the customer to checkout, then verify server-side before you fulfil.

1 · Create a payment session

POST/api/business/payments/sessionx-api-key

Request

curl -X POST https://api.northpoletradelink.com/api/business/payments/session \  -H "x-api-key: sk_live_..." \  -H "Content-Type: application/json" \  -d '{    "amount": 5000,    "currency": "NGN",    "customer_name": "John Doe",    "customer_email": "john@example.com",    "metadata": { "order_id": "ORD-12345" }  }'

2 · Send the customer to checkout

The response carries a checkout_url. Redirect the customer there, or show the returned account details in your own UI so they can transfer directly.

Response · 201

{  "session_id": "ps_abc123def456",  "checkout_url": "https://checkout.northpoletradelink.com/checkout/ps_abc123def456",  "amount": 5000,  "currency": "NGN",  "expires_at": "2026-08-25T12:00:00Z",  "payment_details": {    "account_number": "1234567890",    "bank_name": "Wema Bank",    "account_name": "Acme Corp"  }}

3 · Verify before you fulfil

GET/api/business/payments/session/:sessionId/verifyx-api-key

Response · 200

{  "verified": true,  "session_id": "ps_abc123def456",  "status": "completed",  "amount": 5000,  "paid": true,  "completed_at": "2026-08-25T11:45:00Z"}

Never fulfil on a redirect alone

A customer returning to your success page is not proof of payment, and neither is a webhook on its own. The verify call is the authoritative answer — check paid before releasing anything.

Testing without moving money

With a test-mode key, settle a session by simulation using POST /api/business/payments/session/:sessionId/settle-test. It completes the session and credits your test wallet without calling any external provider.

Best practices

Verify webhook signatures. Always validate X-Northpole-Signature before acting on a payload.
Respond to webhooks fast. Return 2xx within 30 seconds and do the real work in a background job. Anything slower counts as a delivery failure.
Deduplicate deliveries. Use delivery_id to process each delivery exactly once.
Store keys securely. Environment variables or a secrets manager. Never commit a key.
Tell customers sessions expire. One hour. After that the virtual account is deactivated and a late transfer needs manual reconciliation.
Monitor delivery health. Check webhook delivery logs in the dashboard rather than assuming silence means success.