Skip to navigation
API ReferenceTransfers and Debits

Debit customer account

Debits a customer’s account and credits your pool account or one of your business accounts. The amount is in kobo.

The account to debit must be one your business opened for its own customer. Set credit_pool_account to true to credit your pool account, or false and send account_to_credit, which must be your pool account or one of your business accounts.

The request runs as two legs: the debit and then the credit. If the credit fails, Halo reverses the debit.

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.

The idempotency_key is required. Sending a key you already used returns the outcome recorded for it and sends nothing to the bank again. After a refusal or a reversal, use a new key to try again. A 202 means the outcome is unknown: do not retry, and check the reference named in the message with check-transaction-status.

Authentication

AuthorizationBearer

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

Request

This endpoint expects an object.
account_numberstringRequired
The customer account to debit. It must be one your business opened.
amountintegerRequired>=1
Amount in kobo. Must be greater than 0.
credit_pool_accountbooleanRequired

True to credit your pool account. False to credit account_to_credit.

idempotency_keystringRequired<=64 characters
Your unique key for this request, at most 64 characters.
account_to_creditstring or nullOptional

Required when credit_pool_account is false. Your pool account or one of your business accounts.

narrationstring or nullOptional<=100 characters
Narration, at most 100 characters. Defaults to "Debit Account".

Response

Both legs succeeded.
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