Initiate Payment
POST/api/v1/MpesaUssd/direct/transaction-initiate
Send a direct payment request to a customer M-Pesa account.
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| description | string | Yes | Payment description |
| imageUrl | string | No | Public image URL for checkout |
| amount | number | Yes | Payment amount |
| currency | string | Yes | Currency code (ETB, USD, etc.) |
| phone | string | Yes | Customer phone in country-code format without plus sign |
| MerchantOrderId | string | Yes | Unique merchant order ID |
| callbackUrl | string | Yes | Webhook URL for status updates |
| cancelRedirectUrl | string | No | Redirect URL on cancel |
| failedRedirectUrl | string | No | Redirect URL on failure |
| complitedUrl | string | No | Redirect URL on success |
| order.items | array | Yes | Order line items collection |
| order.items[].itemName | string | Yes | Item name |
| order.items[].price | number | Yes | Item price |
| order.items[].quantity | number | Yes | Item quantity |
Example Request
curl --location '/api/v1/MpesaUssd/direct/transaction-initiate' \
--data '{
"description": "Afropay Order Checkout",
"imageUrl": "https://yourapp.com/images/logo.png",
"amount": 1.18,
"currency": "ETB",
"phone": "251900000000",
"MerchantOrderId": "TXN_123456789",
"cancelRedirectUrl": "https://yourapp.com/payment/cancel",
"callbackUrl": "https://yourapp.com/payment/callback",
"failedRedirectUrl": "https://yourapp.com/payment/failed",
"complitedUrl": "https://yourapp.com/payment/success",
"order": {
"items": [
{
"itemName": "Premium Package",
"price": 1.18,
"quantity": 1
}
]
}
}'Example Response
{
"isSuccess": true,
"statusCode": 0,
"message": "Transaction successfully registered",
"data": {
"paymentUrl": "https://client-checkout.afropays.co/checkout/TXN2026012808112471",
"refrence": "TXN2026012808112471"
}
}Customer receives a USSD prompt and authorizes by entering Mpesa PIN.