NIBSS / NIP API

Integrate NIBSS / NIP through the KeyBS Pay unified /v1/payouts REST endpoint. Authentication, request/response, sandbox, webhooks, errors and rate limits.

Speed

Real-time

Currency

NGN

Method key

nibss

Countries

Request sandbox key Full developer docs

NIBSS / NIP integrates through the same POST /v1/payouts endpoint used for every KeyBS Pay corridor — you set "method": "nibss" and the router selects the NIBSS / NIP rail. If NIBSS / NIP is unavailable for the beneficiary bank at the moment of payment, the router falls back to the next eligible rail unless "strict": true is specified.

Authentication is via a Bearer API key issued from the KeyBS Pay dashboard. Every request MUST include an Idempotency-Key so retries after transient errors are safe. Webhook payloads carry an HMAC-SHA256 signature you must verify with your webhook secret before acting on the event.

Sandbox mode is available end-to-end: keys prefixed sk_test_ hit the sandbox environment, produce deterministic responses for testing, and never move real money. Production sk_live_ keys unlock the NIBSS / NIP rail once your KYB is approved.

Corridor data

Corridor mechanics at a glance

Every KeyBS Pay payout follows the same operational contract; only the rail changes.

Endpoint

POST /v1/payouts

Rail method key

"method": "nibss"

Settlement currency

NGN

Countries

Speed

Real-time

Auth

Bearer token · Idempotency-Key header · request-signed HMAC (optional)

Rate limit

600 req/min per API key · burst 60/s

Webhooks

payout.created · payout.approved · payout.settled · payout.failed — HMAC-SHA256 signed with your webhook secret

TL;DR — key takeaways

POST /v1/payouts with method="nibss" routes through the NIBSS / NIP rail.
Settlement: Real-time in NGN · countries: NG.
Bearer-token auth · Idempotency-Key required · HMAC-signed webhooks.
Rate limit: 600 req/min per API key · burst 60/s.
Sandbox available via sk_test_ keys; production sk_live_ keys unlock the rail after KYB.

Request

POST /v1/payouts

POST https://api.keybs.io/v1/payouts
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "amount": { "value": "1000.00", "currency": "USD" },
  "beneficiary": {
    "name": "Acme Trading Ltd",
    "account_number": "0123456789",
    "country": "NG",
    "currency": "NGN"
  },
  "method": "nibss",
  "reference": "INV-2026-0001",
  "purpose_code": "supplier_settlement",
  "metadata": { "invoice_id": "INV-2026-0001" }
}

Response

201 Created

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "po_01HZY8V7BQXP5F3AR2E9N4S6K1",
  "status": "approved",
  "amount":       { "value": "1000.00", "currency": "USD" },
  "beneficiary_amount": { "value": "..." /* rail-specific FX */ },
  "rail":         "nibss",
  "estimated_settlement": "seconds",
  "reference":    "INV-2026-0001",
  "created_at":   "2026-02-14T09:12:00Z"
}

Webhook event

payout.settled — HMAC-signed

POST https://your-app.example/webhooks/keybs
X-KeyBS-Signature: t=1707902000,v1=<HMAC-SHA256(webhookSecret, timestamp + '.' + rawBody)>
Content-Type: application/json

{
  "id":   "evt_01HZY8V7BQXP5F3AR2E9N4S6K1",
  "type": "payout.settled",
  "data": {
    "id":       "po_01HZY8V7BQXP5F3AR2E9N4S6K1",
    "rail":     "nibss",
    "status":   "settled",
    "settled_at": "2026-02-14T09:12:07Z"
  }
}

Error format

422 Unprocessable Entity

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": {
    "code":    "beneficiary_verification_failed",
    "message": "Beneficiary account not found on NIBSS / NIP",
    "rail":    "nibss",
    "retryable": false
  }
}

Ask KeyBS AI