Bank Payouts

Bank Payouts allow you to send funds directly to a recipient’s bank account.

Alexpay processes the payout securely through connected banking networks and provides real‑time updates via webhook notifications and the payout status endpoint.

1. Initiate Bank Payout:

Use this endpoint to initiate a payout to a beneficiary’s bank account.

POST /v1/payment/payouts/process

Headers

Name	Type	Description
secret-key	string	Your Alexpay secret key
public-key	string	Your Alexpay public-key

Request body

• amount (integer): The amount of money to be processed for the payout. This value must be a positive integer.

• countryId (string): A unique identifier for the country where the payout is being processed. This should correspond to a valid country ID. Use the Get countries endpoint

• narration (string: optional): A brief description or note regarding the payout. This helps in identifying the purpose of the transaction.

• transfer_to(string): Must be "bank" for bank payouts.

• bank_id(string): Unique ID representing the beneficiary’s bank. Use the Get bank Id endpoint.

• account_number (string, ): Beneficiary’s bank account number..

• webhook_url(sting: optional):

Request

For example, you can make a post request to the endpoint above and pass in the raw json data bellow.

{
    "amount": 5,
    "countryId": "{{ghana_country_id}}",
    "narration": "Invoice payment",
    "webhook_url": "{{webhook_url}}",
    "transfer_to": "bank",
    "bank_id": "e2638454-bd13-5fe6-8dda-cf0f8ead23d4",
    "account_number": "1441001803779"
}

Response body

On a successful request, the API will return a response with the following structure:

• status (string): The status of the payout request. This may provide additional context on the transaction's result.

• code (integer): A numerical code indicating the outcome of the request. A code of 0 typically indicates success.

• message (string): A message providing further details about the request status.

• data (object): An object containing additional details about the payout, including:

• amount (integer): The amount processed in the payout.

• payout_id (string): A unique identifier for the payout transaction.

• status (string): The current status of the payout.

{
    "status": "success",
    "code": 200,
    "message": "Payout completed successfully",
    "data": {
        "reference": "PY_812f4e79002d4e9&&&&&&&&",
        "status": "successful",
        "amount": 1,
        "message": "transaction completed successfully",
        "operator": ""
    }
}

Payout Status Flow

A mobile money payout typically transitions through these statuses:

• processing/Pending – Alexpay is processing the payout with the mobile money provider.

• success – The payout was delivered successfully.

• failed – The payout could not be completed (network issue, invalid number, insufficient funds, etc.).

Receive Webhook Notifications

Alexpay automatically sends a webhook to your webhook_url every time the payout status changes.