M-Pesa Mobile Money Payout (Kenya)

This guide explains how to integrate mobile money payouts to M-Pesa wallets in Kenya using PayOS.

Overview

M-Pesa is Kenya’s leading mobile money service, enabling businesses to send payouts directly to recipient mobile wallets. By integrating M-Pesa payouts with PayOS, you can efficiently disburse funds to recipients across Kenya.

Supported Currency & Country

Request Structure

M-Pesa payouts in Kenya require the following structure:

Required Fields

Top-Level Fields:

• merchantId: Your merchant identifier
• merchantReference: Unique reference for this payout (UUID recommended)
• amount: Amount in minor units (e.g., 2000 = 20.00 KES)
• currency: Currency code (KES)
• paymentMethodId: Set to "mobilemoney"
• paymentLocation: Set to "KEN" for Kenya
• attributes: Can be an empty object {} or contain additional attributes

Recipient Fields:

• recipient.type: Set to "mobile_money"
• recipient.name: Full name of the recipient
• recipient.operator: Set to "mpesa"
• recipient.country: Set to "KEN" for Kenya
• recipient.phoneNumber: Recipient’s M-Pesa registered phone number

Usage Example

1
{
2
  "merchantId": "your-merchant-id",
3
  "merchantReference": "PAYOUT_550e8400-e29b-41d4-a716-446655440000",
4
  "amount": 2000,
5
  "currency": "KES",
6
  "paymentMethodId": "mobilemoney",
7
  "paymentLocation": "KEN",
8
  "attributes": {},
9
  "recipient": {
10
    "type": "mobile_money",
11
    "name": "John Doe",
12
    "operator": "mpesa",
13
    "country": "KEN",
14
    "phoneNumber": "254723993187"
15
  }
16
}

Expected Response:

1
{
2
    "transactionId": "019b024f-8c57-777f-a97c-fa21a2bdbb40",
3
    "status": "RECEIVED",
4
    "message": "Transaction queried successfully",
5
    "merchantReference": "PAYOUT_db605861-8725-460b-be00-a0740b889944",
6
    "identifiers": {},
7
    "paymentAttributes": {
8
        "merchant_type": "sandbox"
9
    },
10
    "paymentMethodId": "mobilemoney"
11
}

Phone Number Format

Phone numbers are automatically normalized to the required international format (e.g., adding the country code if missing, stripping + prefix). You can provide numbers in either local (e.g., 07...) or international (e.g., +254... or 254...) format.

Valid Phone Number Formats

Amount Limits

M-Pesa enforces the following limits on payouts:

Note: Amounts are specified in minor units. For KES, the minor unit is cents, so 2000 represents 20.00 KES.

Error Codes

The following error codes may be returned for M-Pesa payout failures:

Important Notes

1. Operator Code: Always use "mpesa" as the operator code for M-Pesa payouts in Kenya.

2. Country Code: Use the 3-letter ISO country code "KEN" for both paymentLocation and recipient.country.

3. Currency: Only KES (Kenyan Shilling) is supported for M-Pesa payouts in Kenya.

4. Asynchronous Processing: Payouts are processed asynchronously. After submission, the initial status will be Pending. Monitor the final status via webhooks or by polling the transaction status endpoint.

5. Idempotency: Use unique merchantReference values for each payout request. Duplicate references will be rejected to prevent duplicate payouts.

Best Practices

• Monitor Webhook Events: Ensure your webhook handlers correctly process status updates for both successful and failed payouts.

• Validate Phone Numbers: Before submitting payouts, validate that recipient phone numbers are in a valid format to reduce failed transactions.

Next Steps

Contact your account manager to enable M-Pesa payouts for your merchant account.