Skip to navigation
API ReferenceTransfers and Debits

Same-bank transfer

Sends money between two accounts at Halo. The amount is in kobo.

The money leaves FromAccountNumber, which must be your pool account or an account your business opened. When it is left out, your pool account is used. 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.
ToAccountNumberstringRequired
The account to credit.
RetrievalReferencestringRequired<=12 characters
Your unique reference for this transfer, at most 12 characters.
NarrationstringRequired<=100 characters
Narration, at most 100 characters.
FromAccountNumberstring or nullOptional
The account to debit. Defaults to your pool account.

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