Mobile Money Payouts

The Mobile Money Payout API allows you to send funds directly to a recipient’s mobile wallet.

Alexpay processes the payout on your behalf and provides real‑time updates through webhook notifications and the status API.

1. Initiate Mobile Money Payout

This endpoint is used to start a payout request. You must provide the amount, country, recipient’s mobile money number, and webhook URL to receive updates on the payout status.

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.

• transfer_to(string): This is the payment method. (mobile_number, bank)

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

• momo_phone_number (string, optional): The mobile money phone number to which the payout will be sent. If this is not provided, the payment will be credited to the merchant's momo account.

• 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":26,
    "countryId": "{{zambia_country_id}}",
    "transfer_to": "mobile_number",
    "momo_phone_number": "",
    "webhook_url": "",
    "narration":"testing" //optional
}

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 queued successfully",
    "data": {
        "amount": 26,
        "message": "Payout is being processed by the provider",
        "payout_id": "011fc**********************",
        "status": "processing"
    }
}

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.