Kenyan Shilling (KES) Payouts

This guide explains how to integrate Mavapay’s payout functionality for sending money to Kenyan recipients through mobile money and M-Pesa payment modes.

Overview

The KES payout process involves the following steps:

Choose the appropriate payment mode (mobile money or M-Pesa paybill/till)
Create a quote with the required beneficiary details
Pay the generated lightning invoice
Receive webhook notifications for payment status

Note: KES pay-to-phone payouts support M-Pesa and Airtel Mobile Money. Pay to Bill and Pay to Till are processed through M-Pesa.

Prerequisites

Before you begin, ensure you have:

Created a Mavapay account
Obtained your API key
Set up your webhook endpoint
Verified your business account

Authentication

All API requests must include your API key in the header:

X-API-KEY: your_api_key_here

Important Notes:

All amounts are in cents (1 KES = 100 cents)
The minimum amount for KES payouts is $2
Phone numbers must be in international format (e.g., +254…)
Pay-to-phone quotes require a network field: "mpesa" or "airtel"
Account numbers for paybill payments can be text (usually business name or identifier)
Pay to Bill and Pay to Till are processed through M-Pesa’s payment infrastructure

Payment Modes

KES payouts support the following modes:

1. Pay to Phone (Mobile Money)

Send money directly to a recipient’s M-Pesa or Airtel Mobile Money account. You must specify the target network in beneficiary.identifiers.network.

Starting July 12, 2026, the network field is required for all pay-to-phone KES quotes. Requests missing this field will return a validation error.

curl --request POST \
  --url https://staging.api.mavapay.co/api/v1/quote \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: your_api_key_here' \
  --data '{
  "amount": 500000,
  "sourceCurrency": "BTCSAT",
  "targetCurrency": "KESCENT",
  "paymentMethod": "LIGHTNING",
  "paymentCurrency": "KESCENT",
  "autopayout": true,
  "beneficiary": {
    "identifierType": "paytophone",
    "identifiers": {
      "phoneNumber": "+254796980788",
      "accountName": "John Doe",
      "network": "mpesa"
    }
  }
}'

2. Pay to Bill (M-Pesa Paybill)

Pay to a business using their M-Pesa paybill number:

curl --request POST \
  --url https://staging.api.mavapay.co/api/v1/quote \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: your_api_key_here' \
  --data '{
  "amount": 500000,
  "sourceCurrency": "BTCSAT",
  "targetCurrency": "KESCENT",
  "paymentMethod": "LIGHTNING",
  "paymentCurrency": "KESCENT",
  "autopayout": true,
  "beneficiary": {
    "identifierType": "paytobill",
    "identifiers": {
      "paybillNumber": "4141031",
      "accountNumber": "business_name"
    }
  }
}'

3. Pay to Account/Till (M-Pesa Till)

Pay to a business M-Pesa till number:

curl --request POST \
  --url https://staging.api.mavapay.co/api/v1/quote \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: your_api_key_here' \
  --data '{
  "amount": 500000,
  "sourceCurrency": "BTCSAT",
  "targetCurrency": "KESCENT",
  "paymentMethod": "LIGHTNING",
  "paymentCurrency": "KESCENT",
  "autopayout": true,
  "beneficiary": {
    "identifierType": "paytotill",
    "identifiers": {
      "accountNumber": "till_number"
    }
  }
}'

Understanding the Quote Response

Sample response:

{
  "status": "ok",
  "data": {
    "id": "d1614a76-9c7f-4111-98a7-43199f307e5b",
    "exchangeRate": 4874805.75,
    "usdToTargetCurrencyRate": 145.977,
    "sourceCurrency": "BTCSAT",
    "targetCurrency": "KESCENT",
    "transactionFeesInSourceCurrency": 13.23,
    "transactionFeesInTargetCurrency": "3750.00",
    "amountInSourceCurrency": 1499,
    "amountInTargetCurrency": "50000.00",
    "paymentMethod": "LIGHTNING",
    "expiry": "2021-07-01T12:00:00Z",
    "isValid": true,
    "invoice": "lntbs36020n1pnehfzcpp...",
    "hash": "189727ef2e0f35921af7858b96e27cbad960b0ec2bb2a4ab73b6a231f9ce8727",
    "totalAmountInSourceCurrency": 1499,
    "customerInternalFee": 0
  }
}

Key fields:

usdToTargetCurrencyRate: Price of 1 USD in KES
exchangeRate: Price of 1 BTC in KES
amountInSourceCurrency: Total amount in SATS to be paid (including fees)
amountInTargetCurrency: Total amount in cents to be sent to recipient
transactionFeesInSourceCurrency: Fees in SATS
transactionFeesInTargetCurrency: Fees in cents
expiry: Invoice validity (5 minutes)

Webhook Events

You’ll receive two webhook events:

payment.received - When the lightning payment is received
payment.sent - When the money is sent to the recipient

payment.received Event

{
  "event": "payment.received",
  "data": {
    "id": "tx_123456789",
    "amount": 500000,
    "currency": "KES",
    "status": "SUCCESS",
    "kesTransactionMetadata": {
      "hash": "189727ef2e0f35921af7858b96e27cbad960b0ec2bb2a4ab73b6a231f9ce8727",
      "reference": "MP123456789"
    }
  }
}

payment.sent Event

{
  "event": "payment.sent",
  "data": {
    "id": "tx_123456789",
    "amount": 500000,
    "currency": "KES",
    "status": "SUCCESS",
    "kesTransactionMetadata": {
      "identifierType": "paytophone",
      "phoneNumber": "+254796980788",
      "network": "mpesa",
      "reference": "MP123456789"
    }
  }
}

Checking Transaction Status

You can query transactions using the payment hash, orderId, or transaction ID:

# Using hash
curl --location 'https://staging.api.mavapay.co/api/v1/transaction?hash=08f7198fd7dd73c087b4754a20d6f63f5b87bb8fcdc10e4d5cacd27650fce2ba' \
--header 'x-api-key: your_api_key_here'

# Using transaction ID
curl --location 'https://staging.api.mavapay.co/api/v1/transaction?id=7bac35f1-2efc-448b-8a71-0d071da43315' \
--header 'x-api-key: your_api_key_here'

Getting Price Rates

To get current KES rates:

curl --location 'https://staging.api.mavapay.co/api/v1/price?currency=KES'

Sample response:

{
  "status": "ok",
  "data": {
    "currency": "KES",
    "timestamp": 1738258609,
    "btcPriceInUnitCurrency": 4874805.75,
    "unitPricePerSat": {
      "amount": 0.04874805,
      "currencyUnit": "KESSAT"
    },
    "unitPricePerUsd": {
      "amount": 145.977,
      "currencyUnit": "KESUSD"
    }
  }
}

Testing

Use our staging environment for testing:

https://staging.api.mavapay.co/api/v1

Test details:

Phone Number: +254790000000
Paybill Number: 4141031
Account Number: test_account
Till Number: 000000

Note: All test environment invoices are signet invoices.

Support

If you need help with integration:

Email: info@mavapay.co
Documentation: https://docs.mavapay.co
API Reference: https://docs.mavapay.co/api-reference

Get Started

Payouts

Webhooks

Guides

Kenyan Shilling (KES) Payouts

Kenyan Shilling (KES) Payouts

Overview

Prerequisites

Authentication

Payment Modes

1. Pay to Phone (Mobile Money)

2. Pay to Bill (M-Pesa Paybill)

3. Pay to Account/Till (M-Pesa Till)

Understanding the Quote Response

Webhook Events

payment.received Event

payment.sent Event

Checking Transaction Status

Getting Price Rates

Testing

Support

​Kenyan Shilling (KES) Payouts

​Overview

​Prerequisites

​Authentication

​Payment Modes

​1. Pay to Phone (Mobile Money)

​2. Pay to Bill (M-Pesa Paybill)

​3. Pay to Account/Till (M-Pesa Till)

​Understanding the Quote Response

​Webhook Events

​payment.received Event

​payment.sent Event

​Checking Transaction Status

​Getting Price Rates

​Testing

​Support

Kenyan Shilling (KES) Payouts

Overview

Prerequisites

Authentication

Payment Modes

1. Pay to Phone (Mobile Money)

2. Pay to Bill (M-Pesa Paybill)

3. Pay to Account/Till (M-Pesa Till)

Understanding the Quote Response

Webhook Events

payment.received Event

payment.sent Event

Checking Transaction Status

Getting Price Rates

Testing

Support