Skip to navigation
API ReferenceTransfers and Debits

Debit account

Debits an account your business opened. The money goes to the bank and is not credited to an account you name. The amount is in kobo.

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.
retrieval_referencestringRequired<=12 characters
Your unique reference for this debit, at most 12 characters.
account_numberstringRequired
An account number your business opened.
amountintegerRequired>=1
Amount in kobo. Must be greater than 0.
narrationstring or nullOptional<=100 characters
Narration, at most 100 characters. Defaults to "Debit Account".
nibss_codestring or nullOptional
NIBSS institution code.

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
404
Not Found Error
422
Unprocessable Entity Error
429
Too Many Requests Error