Skip to main content

NIP Transfers

The NIP (NIBSS Instant Payment) integration handles real-time interbank transfers across the Nigerian banking system. This guide covers the full lifecycle — outbound transfers, inbound credits, name enquiry, reversals, and the CBN-mandated fee structure.

Outbound NIP Transfers​

Outbound transfers follow a saga pattern to ensure consistency:

Debit Source Account
  │
  ▼
Send to NIP Provider (Interswitch / NIBSS)
  │
  ▼
Post GL Journal (debit customer, credit NIP in-transit)
  │
  ▼
Mark Complete / Handle Failure

Submit an Outbound Transfer​

POST /api/v1/transfers/interbank
curl -X POST https://api.korastratum.com/api/v1/cba/transfers/interbank \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: demo_bank" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: nip-$(uuidgen)" \
  -d '{
    "source_account_id": "acct-uuid",
    "destination_account_num": "0123456789",
    "destination_bank_code": "058",
    "destination_account_name": "JANE SMITH",
    "amount": 50000.00,
    "currency": "NGN",
    "channel": "API",
    "narration": "Invoice payment",
    "initiated_by": "user-uuid"
  }'

Response:

{
  "id": "txn-uuid",
  "transaction_ref": "TRN20260407001234",
  "transaction_type": "TRANSFER",
  "transfer_type": "INTERBANK",
  "status": "PROCESSING",
  "source_account_id": "acct-uuid",
  "source_account_num": "1001234567",
  "dest_account_num": "0123456789",
  "dest_account_name": "JANE SMITH",
  "dest_bank_code": "058",
  "dest_bank_name": "Guaranty Trust Bank",
  "amount": 50000.00,
  "fee": 26.88,
  "vat": 2.02,
  "total_amount": 50028.90,
  "session_id": "000012260407100012345678",
  "channel": "API",
  "narration": "Invoice payment"
}
note

Outbound transfers return status PROCESSING immediately. Use the session ID or transaction reference to poll for final status, or subscribe to the transfer.completed / transfer.failed webhooks.

Inbound NIP Credits​

When another bank sends funds to your customer via NIP, the platform receives an inbound credit notification.

POST /api/v1/transfers/nip/inbound

The inbound flow:

  1. Validate — Verify the destination account exists and is active.
  2. Credit — Credit the customer's account with the received amount.
  3. GL Post — Debit NIP in-transit, credit customer deposit liability.
  4. Notify — Emit transfer.inbound webhook event and push notification.

Inbound payload (received from NIP):

{
  "session_id": "000058260407143012345678",
  "source_bank_code": "058",
  "source_account_num": "0123456789",
  "source_account_name": "JANE SMITH",
  "destination_account_num": "1001234567",
  "amount": 50000.00,
  "narration": "Payment for services",
  "transaction_date": "2026-04-07T14:30:00Z"
}
tip

Inbound credits are processed automatically. You do not need to call this endpoint directly — the NIP gateway handles it. Subscribe to the transfer.inbound webhook to react to incoming funds.

Name Enquiry​

Validate an account at another bank before initiating a transfer. The service tries Interswitch as the primary provider and falls back to NIBSS if unavailable.

POST /api/v1/transfers/validate-account
curl -X POST https://api.korastratum.com/api/v1/cba/transfers/validate-account \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: demo_bank" \
  -H "Content-Type: application/json" \
  -d '{
    "account_number": "0123456789",
    "bank_code": "058"
  }'

Response:

{
  "account_number": "0123456789",
  "account_name": "JANE SMITH",
  "bank_code": "058",
  "bank_name": "Guaranty Trust Bank",
  "provider": "INTERSWITCH"
}
note

Name enquiry uses Interswitch as the primary provider with automatic NIBSS fallback. The provider field indicates which service resolved the enquiry.

NIP Reversals​

When an outbound NIP transfer fails after the customer has been debited, a reversal is triggered to restore the funds.

POST /api/v1/transfers/nip/reversal

The reversal flow:

  1. Credit the customer's account with the original debit amount.
  2. Reverse GL — Create a reversing journal (debit NIP in-transit, credit customer account).
  3. Update the original transaction status to REVERSED.
curl -X POST https://api.korastratum.com/api/v1/cba/transfers/nip/reversal \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: demo_bank" \
  -H "Content-Type: application/json" \
  -d '{
    "original_session_id": "000012260407100012345678",
    "original_transaction_ref": "TRN20260407001234",
    "reason": "TIMEOUT",
    "initiated_by": "system"
  }'
warning

Reversals are idempotent. Attempting to reverse an already-reversed transaction returns the existing reversal record. Only transactions with status FAILED or TIMEOUT can be reversed.

Bank List​

Retrieve the full list of supported Nigerian banks with their CBN and NIP codes.

GET /api/v1/transfers/banks

Returns 28+ banks. Example entries:

Bank NameCBN CodeNIP Code
Access Bank044044
First Bank of Nigeria011011
Guaranty Trust Bank058058
United Bank for Africa033033
Zenith Bank057057
Stanbic IBTC Bank221221
Fidelity Bank070070
Sterling Bank232232
Wema Bank035035
Polaris Bank076076

Fee Structure​

NIP transfer fees follow CBN-mandated tiers. Fees are automatically calculated and included in the transaction response.

Amount RangeFee (excl. VAT)VAT (7.5%)Total Fee
₦1 – ₦5,000₦10.75₦0.81₦11.56
₦5,001 – ₦50,000₦26.88₦2.02₦28.90
₦50,001+₦53.75₦4.03₦57.78
note

These are the CBN-mandated maximum fees. Your tenant configuration may apply lower fees. Fee configuration is managed via the Transactions fee setup.

Next Steps​