Skip to content
BankCore Partner API

Interbank transfer (NIP)

An interbank transfer debits an account you may debit, your own or an agent’s in your estate (see Ownership model), and pays an account at another bank through NIBSS Instant Payment (NIP). The call is synchronous: the platform debits, sends, and then waits up to about 35 seconds for NIBSS’s answer before replying. Most transfers finish inside that window. The ones that do not are told so honestly with 0009, and the platform keeps chasing them for you.

Do a name enquiry first and echo its fields; NIBSS expects them, and the bank’s reviewers expect to see a verified beneficiary name.

POST/api/legacy/provider/wallets/transactions/banktransferscope: nip:transfer

Request

Section titled “Request”
Field Type Required Description
fromAccountNumber string Yes 10-digit source account. Must be yours to debit: your own account, or an agent’s with sub-agent access and sub-agents:debit (see Ownership model).
toAccountNumber string Yes Beneficiary NUBAN at the other bank.
destinationBankCode string Yes 3-digit CBN code or 6-digit NIBSS code, from the institutions list. Stored and reported as the 6-digit form.
amount decimal Yes Naira. At most ₦5,000,000 per transfer; split larger amounts yourself.
toAccountName string No Beneficiary name from the name enquiry. Defaults to Beneficiary if omitted; always send it.
memo string No Narration, shown on the statement and sent to NIBSS.
transactionRef string No Your reference. Unique per tenant among interbank transfers. Strongly recommended.
beneficiaryBvn, beneficiaryIdType, beneficiaryAccountDesignation, beneficiaryKycTier string No Echoed from the name enquiry.
nameEnquirySessionId string No Echoed from the name enquiry.
Terminal window
curl -X POST https://api.bankcore.ng/api/legacy/provider/wallets/transactions/banktransfer \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fromAccountNumber": "6020012345",
    "toAccountNumber": "0123456789",
    "toAccountName": "ADEBAYO OGUNDIMU",
    "destinationBankCode": "058",
    "amount": 25000.00,
    "memo": "Invoice 1234",
    "transactionRef": "PAY-20260401-001",
    "nameEnquirySessionId": "100003260401143000000001"
  }'

What happens

Section titled “What happens”

  1. Everything that can be refused is refused before any debit: the ₦5,000,000 cap, a reused transactionRef, an unknown bank code, an account you may not debit, an inactive account, insufficient funds for principal plus fees, and velocity limits.

  2. The source account is debited: the principal, then separate fee, VAT and stamp duty lines where the bank charges them (see Fees). A NIP session id is generated and stored.

  3. The transfer is handed to NIBSS and the call waits for the outcome, up to about 35 seconds.

  4. The reply reports whatever state the transfer is in when the wait ends.

Response

Section titled “Response”
{
  "code": "0000",
  "desc": "Successful",
  "retRef": "NIP20260401143000AB12CD",
  "clientRef": "PAY-20260401-001",
  "fromAccount": "6020012345",
  "toAccount": "0123456789",
  "availableBalance": "124923.12",
  "ledgerBalance": "124923.12",
  "transdatetime": "20260401143012",
  "sessionId": "100003260401143000000042"
}
Field Description
code 0000, 0009 or 0096; see below.
retRef BankCore’s transfer reference, NIP….
clientRef Your transactionRef, echoed.
sessionId The NIP session id. Its first six characters are the bank’s institution code. This is what the beneficiary’s bank will ask for; store it with the payment.
availableBalance, ledgerBalance The source account after principal and fees.

Reading the code

Section titled “Reading the code”
Code Transfer state Meaning What to do
0000 COMPLETED NIBSS confirmed the credit. Money has left and the beneficiary is paid. Done.
0096 FAILED / REVERSED NIBSS rejected it, or it failed; desc carries the NIBSS reason. The debit and the fee lines have been refunded. Fix the cause and resend with a new transactionRef.
0009 PROCESSING or UNDER_INVESTIGATION The source account is debited and the outcome is not yet known: the wait expired with NIBSS still processing, or the platform has already handed it to the bank’s operations team. Do not resend. Track it as below. The platform resolves it: completed, or refunded.

Errors before the debit

Section titled “Errors before the debit”

These all come back without any money moving.

Code When
0004 Available balance is below principal plus fees. desc shows both figures.
0012 Over the ₦5,000,000 cap; missing bank code, account or amount; the source is not yours to debit; the source account does not exist.
0062 The source account is not active.
0094 transactionRef already used on an interbank transfer.
0096 Unknown destinationBankCode; a velocity limit on the source customer; a synchronous rejection by NIBSS (Transfer rejected by NIBSS: …), in which case the debit was taken and immediately refunded; or a system error.

The five customer-facing states

Section titled “The five customer-facing states”

The platform tracks eight internal states; you and the portal see five.

You see Internal Meaning
PROCESSING INITIATED, DEBITED, SENT Debited; outcome pending.
COMPLETED CONFIRMED, SETTLED Beneficiary paid. SETTLED adds that NIBSS has settled the bank’s position, which changes nothing for you.
FAILED FAILED Did not happen.
REVERSED REVERSED Did not happen, and the money has been returned. In practice every failure is immediately reversed, so this is the state you will see.
UNDER_INVESTIGATION ESCALATED The platform could not establish the outcome automatically. The bank’s operations team owns it; the money is held, not lost.

Tracking a transfer

Section titled “Tracking a transfer”

For a 0009, in order of usefulness:

  • Webhooks. nip.transfer.completed and nip.transfer.failed carry your reference and the session id; transaction.reversed follows a refund. See Events and payloads.
  • The portal. The Interbank transfers page shows the current state for every transfer.
  • Your relationship manager, with the sessionId, for anything still open after a day.

Check a transaction with your reference answers for the debit, which is COMPLETED as soon as the source account is debited, whatever NIBSS later says. It does not report the NIP state. A refund appears as a separate REVERSAL line on the statement.

How the platform resolves it

Section titled “How the platform resolves it”
  • Every five minutes a job re-queries NIBSS for each transfer still in flight, up to 10 times (about 50 minutes).
  • A confirmation completes it; a definite rejection reverses it. Both fire the webhooks above.
  • NIBSS answering “timeout” or “system error” (97, 96) on four consecutive queries is treated as a failure and the debit is refunded.
  • NIBSS answering “no such transaction” (25) is not acted on: that code has been returned for transfers that did settle. The transfer keeps being queried, and the next day’s NIBSS settlement file decides it.
  • A transfer that was never actually dispatched (no session id) is refunded straight away.
  • When the queries are exhausted, or a transfer is older than 20 hours (past which NIBSS’s status service is unreliable), it becomes UNDER_INVESTIGATION and a case is opened for the bank’s operations team. They complete it or refund it, manually.

Reversals are therefore automatic on a provider-confirmed failure and investigated when the answer is ambiguous. A refund restores the principal and every fee line.

Agent twin

Section titled “Agent twin”
POST/api/legacy/agent/transact/transfer/direct_debitscope: nip:transfer

The same transfer from a sub-agent’s transaction account, named by the X-Agent-Account header; fromAccountNumber is ignored. Requires sub-agents:debit. Despite its name this is an ordinary NIP credit transfer, not a direct debit. Same body, reply and codes; the reply reports the agent’s balance and the transaction metadata is stamped initiatedByPartner.

In the portal

Section titled “In the portal”

The Interbank transfers page lists every transfer, inward and outward, filterable by the five states, with your reference, the counterparty and the sessionId. A transfer’s detail page shows the three money moments (debited, completed, returned) and, on a failed or returned one, the NIBSS response code with its published meaning. A completed outward transfer has a printable receipt carrying the session id. The register exports to CSV or XLSX.