Kenya
M-Pesa and Airtel mobile money payments in KES
Before you start
Authorization
How to sign your requests with the API token.
Create payment
The base order request that this page extends.
This payment method is not enabled for all merchants. Check availability with your manager.
Overview
| Currency | Country code | Payment method |
|---|---|---|
KES | KE | M-Pesa, Airtel (mobile money) |
Two scenarios are available. Which scenario and which operator are enabled for your account is defined by your terminal settings.
Not sure which option you have? Ask your manager.
What is different from a regular order
The order is created through the standard POST /v1/orders endpoint. The base fields (amount, currency, successUrl, failUrl, callbackUrl, etc.) are the same as for a regular order; on top of them you pass the customer object with payer details.
| Field | Type | Description |
|---|---|---|
customer | object | Payer details. The required set is listed below |
The payer is redirected to paymentLink and confirms the payment in M-Pesa.
The externalUserId field is required for this payment method.
Customer fields
| Field | Type | Required | Description |
|---|---|---|---|
country | string | ✅ Yes | Country code, always KE |
phone | string | ⚠️ Depends on the method | Payer phone number, format 254712345678 |
email | string | ✅ Yes | Payer email |
firstName | string | ✅ Yes | First name |
lastName | string | ✅ Yes | Last name |
Request example
{
"purpose": "Payment for order #1234",
"amount": "100",
"currency": "KES",
"externalId": "external_id",
"externalUserId": "external_user_id",
"successUrl": "https://example.com/success",
"failUrl": "https://example.com/fail",
"callbackUrl": "https://example.com/webhooks/payments",
"isFeeOnUser": false,
"customer": {
"firstName": "John",
"lastName": "Doe",
"country": "KE",
"email": "john.doe@example.com"
}
}Operators: M-Pesa, Airtel.
Send the payer to paymentLink: the payment request goes to the operator when the link is opened, and the payer confirms it on their phone (push notification or USSD prompt). The page waits for the result and shows it; the final status also comes to your callbackUrl.
Customer fields
| Field | Type | Required | Description |
|---|---|---|---|
phone | string | ✅ Yes | Payer phone number, digits only with the country code: 254712345678 |
firstName | string | ⚠️ Depends on the operator | First name |
lastName | string | ⚠️ Depends on the operator | Last name |
email | string | ⚠️ Depends on the operator | Payer email |
country | string | ❌ No | Country code KE. Optional: the country is defined by the method |
The required set depends on the operator enabled on your terminal. If a field it needs is missing or the phone does not match the country format, the order is rejected with 400 listing the fields. Send firstName, lastName, email and phone whenever you have them.
Request example
{
"purpose": "Payment for order #1234",
"amount": "1000",
"currency": "KES",
"externalId": "external_id",
"externalUserId": "external_user_id",
"successUrl": "https://example.com/success",
"failUrl": "https://example.com/fail",
"callbackUrl": "https://example.com/webhooks/payments",
"isFeeOnUser": false,
"customer": {
"firstName": "John",
"lastName": "Doe",
"phone": "254712345678",
"email": "john.doe@example.com"
}
}Send whole amounts in KES: some methods do not accept fractional amounts.
Response
The response is a standard order object. The order is created with the CREATED status; redirect the payer to paymentLink to complete the payment.