Skip to navigation
API ReferenceTransfers and Debits

Interbank transfer

Sends money to an account at another bank. The amount is in kobo. Check the receiver with name-enquiry first.

The money leaves PayerAccountNumber, which must be your pool account or an account your business opened. Send PayerAccountNumber and Payer together, or leave both out to use your pool account and business name. Halo adds its fee.

Each request is checked against your per-transaction limit (default 500,000,000 kobo, NGN 5,000,000) and your daily limit (default 5,000,000,000 kobo, NGN 50,000,000). Halo can set different limits for your business. Transfers that are still unconfirmed count toward the daily limit.

Sending a reference you already used returns the outcome recorded for it. Nothing is sent to the bank again, even if the other fields differ. References belong to your business, so another business using the same reference never affects yours.

A 202 means the bank did not prove success or refusal. Do not retry, and never retry with a new reference: the money may already have moved. Check the outcome with check-transaction-status.

Authentication

AuthorizationBearer

Your Halo partner API key, sent as Authorization: Bearer <key>.

Request

This endpoint expects an object.
AmountintegerRequired>=1
Amount in kobo. Must be greater than 0.
TransactionReferencestringRequired<=12 characters
Your unique reference for this transfer, at most 12 characters.
ReceiverBankCodestringRequired
The receiver's bank code.
ReceiverAccountNumberstringRequired
The receiver's account number.
ReceiverNamestringRequired

The receiver’s name, as returned by name-enquiry.

PayerAccountNumberstringOptional
The account to debit. Required when Payer is sent.
PayerstringOptional
The payer name. Required when PayerAccountNumber is sent.
Narrationstring or nullOptional
Narration.
NIPSessionIDstring or nullOptional

The session ID from name-enquiry.

ReceiverPhoneNumberstring or nullOptional
The receiver's phone number.
ReceiverAccountTypestring or nullOptional
The receiver's account type.
ReceiverKYCstring or nullOptional
The receiver's KYC level.
ReceiverBVNstring or nullOptional
The receiver's BVN.

Response

The bank confirmed the transfer.
statusboolean
True on success, false otherwise.
messagestring or map from strings to lists of strings
A short message. On a 422 validation failure it is an object of field names to error lists.
status_codeinteger
The HTTP status code.
dataanyOptional
The result. Left out on most errors.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
422
Unprocessable Entity Error
429
Too Many Requests Error