1. Intrabank Transfer
Virtual Account Services
  • Introduction
  • Terminologies
  • Webhooks
  • Authentication
  • Account
    • Create Account
      POST
    • Balance Inquiry
      GET
    • Rename Account
      POST
    • Create Bulk Accounts
      POST
    • List Accounts
      GET
  • Transaction
    • Credit Account
      POST
    • Debit Account
      POST
    • Credit Account [Agency Banking]
      POST
    • Debit Account [Agency Banking]
      POST
    • Transaction Query
      GET
    • Transaction Details
      GET
    • Transaction History
      GET
  • Transfer
    • Interbank Transfer
      • Interbank Transfer
      • Interbank Transfer [Sync]
      • Transfer Query
      • Transfer Enquiry
    • Intrabank Transfer
      • Intrabank Transfer [Same Groupcode]
        POST
      • Intrabank Transfer [Different Group Codes]
        POST
      • Intrabank Transfer [Savings Account]
        POST
      • Intrabank Transfer Query
        GET
      • Universal Intrabank Transfer
        POST
      • Universal Intrabank Transfer Query
        GET
    • Name Inquiry
      POST
    • Get Institutions
      GET
  • Invoice
    • Create Invoice
    • Get Invoice Detail
    • Get Invoice Status
    • List Merchant Invoices
  • Refunds
    • Get Refunds
    • Initiate Refund
    • Get Refund Status
  • Notifications
    • Notification
    • Send Notification
  • Group Code
    • Create Group Code
  • Overdraft
    • Draw Overdraft
  • Merchant
    • Account
      • Get Account
      • Activate Sub Ledger For Merchant
      • Get SubLedger Callback Urls
      • Set SubLedger Callback Urls
      • Get Collection Accounts
    • Transfer
      • Get Transfer Details
      • Name Inquiry
      • Get Transfer History
      • Get Subledger transfers
    • Refund
      • Refund Details
    • Create Merchant Account
    • Activate Sub Ledger For Merchant
    • Get KYC Information
    • Get Group Code Collection Account
    • Get Collection Accounts
    • Set Collection Account
    • Get Transfer Details
    • Name Inquiry
  • Admin
    • Accounting
      • Get Classification Codes
      • Get GL Accounts
    • Dashboard
      • Dashboard Summary
      • Dashboard Transaction Details
      • Dashboard Transactions
    • Group Codes
      • Create Group Code
      • Set Collection Account
      • Get Group Codes
    • Reporting
      • Get Report Parameters
      • Get Reports
      • Create Report
      • Get Reports Details
      • Get Reports
    • Get Reports
    • Get Report Parameters
  • Schemas
    • VACreateGroupCodeRequest
    • SubLedgerGroup
    • InvalidParameterError
    • TransactionPointError
    • UnauthorizedError
    • UniversalIntrabankTransferResponse
    • SpringDefaultError
  1. Intrabank Transfer

Universal Intrabank Transfer

POST
/transfer/intrabank-universal

Universal Intrabank Transfer#

Moves money from a virtual account (wallet or static account) to any other account of the bank with one call: another virtual account or a core banking account. The bank works out what the destination is and posts every part of the transfer once.
This route only sends money out of virtual accounts. A transfer whose source is a core banking account is refused with SOURCE_IS_CORE_ACCOUNT and nothing is moved; use POST /core/transfer/intrabank-universal for those.
POST /transfer/intrabank-universal
kind in the answerFromTo
VirtualToCoreVirtual accountCore banking account
VirtualToVirtualVirtual accountVirtual account of another parent account (another merchant)
VirtualToVirtualSameParentVirtual accountVirtual account of the same parent account
Never accepted: a core banking account as the source, an invoice account as the source (it can only be paid), and a parent account on either side (it moves only through its virtual accounts). When the destination is an invoice account the invoice is paid: the amount must equal the invoice amount, and the invoice must not be expired or already paid.
There is no fee. The amount must be within the source account's available balance (balance less any blocked amount).

Request Body#

Field NameTypeRequiredDescription
transactionReferencestringTRUEYour unique reference for this transfer, at most 64 characters: letters, digits, ., _ and -. It cannot be only digits, and it cannot contain CBVA, SL-TRSF, _REV, _Credit, _Debit, or both CB and VA, or start with SLF- or Rev:. It is the identity of the transfer (see below)
fromAccountIDstringTRUEThe account to debit, 10 digits. A virtual account (wallet or static). Never a core banking account, an invoice account or a parent account
toAccountIDstringTRUEThe account to credit, 10 digits, different from fromAccountID. Any virtual or core banking account except a parent account
amountdecimalTRUEGreater than zero, at most 2 decimal places, in naira
narrationstringTRUEAt most 150 characters. Cannot start with Rev:

Response Body#

Read outcome first: the HTTP status always agrees with it. code says why when the outcome is not Credited.
Field NameTypeDescription
outcomestringCredited, Pending, Refused or Reversed
codestringSee the codes below. CREDITED when done
messagestringA sentence for logs and operators, not for parsing
transactionReferencestringAs sent
kindstringOne of the five kinds. Absent when the request was refused before it was classified
fromAccountID, toAccountID, amountAs sent
invoiceReferencestringThe invoice paid, when the destination is an invoice account
debitReferencestringThe reference of the debit leg
creditReferencestringThe reference of the credit leg
creditTransactionIdintegerThe core banking transaction of the credit, when the destination is a core banking account
outcomeHTTPMeaningMoney
Credited200Done: the source was debited and the destination creditedMoved, once
Pending202Not finished. Send the same request againMay be debited, never credited twice
Refused409Refused before any money movedNothing moved
Reversed409The source was debited, the destination refused the credit, and the debit was returnedNothing moved in the end
(invalid request)400A field breaks the rules, or the reference is not acceptableNothing recorded

Retrying#

The transactionReference makes every retry safe. Until you hold a final outcome, ask again with the same reference and the same body, never a new reference. To read what happened to a transfer without carrying anything out, call GET /transfer/intrabank-universal/{transactionReference}. To finish a transfer that is still pending, send the same request again.
1.
Create the reference once per customer instruction and save it with the instruction before the first call.
2.
Credited (200): done. Refused or Reversed (409): final, and the customer is not out of pocket. For a new instruction use a new reference.
3.
Pending (202), a timeout, a connection error or a 5xx: keep the instruction pending and send the same request again, for example after 30 seconds, 1 minute, 2 minutes, then every 5 minutes. Do not refund or fail the customer yourself. The bank also finishes unfinished transfers on its own every 2 minutes, so a later call usually returns the final outcome straight away.
4.
Pending with code HELD: the transfer is stopped for a person and the bank has been alerted. Ask less often (hourly) and contact support with the reference.
5.
Once a reference has a final outcome, sending it again is refused with 400 Transaction Reference Already Exists; read the outcome with the GET call instead. The same reference with a different fromAccountID, toAccountID or amount is refused the same way.
6.
Allow at least 120 seconds before timing out, and treat a timeout as Pending.

Codes#

CodeOutcomeMeaningWhat to do
CREDITEDCreditedDoneComplete the instruction
CREDIT_PENDINGPendingDebited; the credit is not posted yetSend the same request again
CREDIT_UNCLEARPendingDebited; the credit has no clear answer yetSend the same request again; it is never credited twice
DEBIT_PENDINGPendingThe debit of a virtual account is not posted yetSend the same request again
DEBIT_UNCLEARPendingThe debit has no clear answer yetSend the same request again; after 30 minutes it ends Credited or DEBIT_NOT_MADE
REVERSAL_PENDINGPendingThe credit was refused; returning the debit is not finishedSend the same request again
IN_PROGRESSPendingAnother call for this reference is runningWait, then send the same request again
NO_ANSWERPendingThe call could not be confirmed (timeout or error)Send the same request again
HELDPendingStopped for a personSee Retrying, point 4
CREDIT_REFUSEDReversedThe destination refused the credit; the debit was returnedFail the instruction; the customer has their money
INVALID_REQUESTRefused (400)A field breaks the rulesFix the request
TRANSFER_DISABLEDRefusedIntrabank transfers are not switched on for this bankDo not offer the transfer
TRANSFER_NOT_CONFIGUREDRefusedThe bank has not finished setting up transfersContact support; nothing moved
GL_MISMATCHRefusedThe two sides would be booked differentlyContact support with both account numbers
REFERENCE_REUSEDRefusedThe reference was used for a different transferUse a new reference
INVALID_SOURCE_ACCOUNTRefusedThe source is not an account here, or is a parent accountCheck the account number
INVALID_DESTINATION_ACCOUNTRefusedThe destination is not an account here, or is the source's own parent accountCheck the account number
SOURCE_IS_INVOICERefusedThe source is an invoice account, which can only be paidChoose another source
SOURCE_IS_CORE_ACCOUNTRefusedThe source is a core banking account, which this route does not send fromUse POST /core/transfer/intrabank-universal; nothing moved
SOURCE_BLOCKED, DESTINATION_BLOCKEDRefusedThe virtual account is blockedTell the customer
DEBIT_REFUSEDRefusedThe debit was refused, for example insufficient available balanceTell the customer; message gives the reason
DEBIT_NOT_MADERefusedNo debit was recorded within 30 minutes of the first callFail the instruction; nothing moved
TRANSFER_REFUSEDRefusedA transfer between virtual accounts was refused as a wholeTell the customer; message gives the reason
INVOICE_NOT_PAYABLERefusedThe invoice is for another amount, expired, or not liveCheck the invoice
INVOICE_CHANGED, INVOICE_NOT_CLAIMEDRefusedThe invoice was paid or changed by another payment meanwhileCheck the invoice

Security#

You may only move money out of a virtual account that belongs to your own parent account, and your API user must be allowed to use this route. A request that breaks either rule is answered 401 and nothing is recorded. Money can be sent to any account of the bank, including the virtual accounts of other merchants.
A reference that was sent to POST /core/transfer/intrabank-universal cannot be used here (400 Transaction Reference Already Exists).

Request

Body Params application/json

Example
{
  "transactionReference": "PAY-2026-0001",
  "fromAccountID": "9000000002",
  "toAccountID": "1000000001",
  "amount": 1500,
  "narration": "Rent November"
}

Request Code Samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location '/transfer/intrabank-universal' \
--header 'Content-Type: application/json' \
--data '{
  "transactionReference": "PAY-2026-0001",
  "fromAccountID": "9000000002",
  "toAccountID": "1000000001",
  "amount": 1500,
  "narration": "Rent November"
}'

Responses

🟢200Credited: the source was debited and the destination credite
application/json
Credited: the source was debited and the destination credited.
Bodyapplication/json

Example
{
  "outcome": "Credited",
  "code": "CREDITED",
  "message": "The destination account was credited from the source account.",
  "transactionReference": "PAY-2026-0001",
  "kind": "VirtualToCore",
  "fromAccountID": "9000000002",
  "toAccountID": "1000000001",
  "amount": 1500.0,
  "debitReference": "IBT-PAY-2026-0001-DR",
  "creditReference": "IBT-PAY-2026-0001-CR",
  "creditTransactionId": 884512
}
🟢202Pending: not finished. Send the same request again.
🟠400| Source | Error | When |
🟠401| Source | Error | When |
🟠409Refused or Reversed: nothing moved in the end. The body is a
🔴500| Source | Error | When |
Modified at 2026-11-22 05:02:29
Previous
Intrabank Transfer Query
Next
Universal Intrabank Transfer Query
Built with