Mobile Money is a popular alternative payment method in Kenya, supported by EBANX to offer a convenient and secure way for customers to complete transactions using their mobile wallets. This method allows Kenyan customers to make purchases directly from their mobile phones, leveraging the local mobile network operators’ infrastructure to access funds. By integrating Mobile Money through EBANX, you can provide Kenyan customers with a trusted, widely used payment option that aligns with local preferences, offering a seamless checkout experience accessible to those without traditional bank accounts.
Requirements
- API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
- Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters.
How it works
- Payment request - Your customer chooses Mobile Money as the payment method at checkout, entering their phone number linked to their mobile wallet.
- PIN confirmation - After initiating the transaction, the customer receives a push notification or SMS prompt from their mobile network operator, requesting a PIN to confirm the payment.
- Real-time authorization - Once the customer enters their PIN, the payment is authorized in real time, providing immediate confirmation to the merchant
- Settlement - EBANX processes the transaction, ensuring funds are transferred securely from your customer’s mobile wallet to your account.
Instructions
Follow the steps below.
Select your environment
Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.
https://sandbox.ebanx.com/ws/directDefine your parameters
Once you’ve defined your parameters, these details will be used to construct the HTTP request, which initiates the Mobile Money transaction and enables EBANX to process the payment accurately and securely.
Basic parameters:
Parameter Description operationSet to requestintegration_keyYour EBANX integration key payment_type_codeChoose a Kenya mobile network operator: mpesa, andairtelcountrySet to kefor KenyaCustomer data:
Parameter Description nameCustomer name emailCustomer e-mail phone_numberCustomer phone number (required) The phone number is crucial for this payment process, as it triggers a push notification prompting the customer to validate and confirm the charge. Be sure to provide it in full international format, including the country code (254 for Kenya).
Charge parameters:
Parameter Description merchant_payment_codeUnique merchant payment code currency_codeSupported values: KESamount_totalTotal amount to be charged Sample request
Use the following example to initiate a request.
curl -X POST \
--location 'https://sandbox.ebanx.com/ws/direct' \
--header 'Content-Type: application/json' \
--data '{
"integration_key": "your_ebanx_integration_key",
"operation": "request",
"payment": {
"name": "John Doe",
"email": "email@example.com",
"phone_number": "254000000000",
"country": "ke",
"payment_type_code": "mpesa", // Mobile network operator.
"merchant_payment_code": "63c9377be268e",
"currency_code": "KES",
"amount_total": "100"
}
}'Sample response
A successful request returns a response like the example below.
{
"payment": {
"hash": "63c9377bf0e9252be9fd2f8424bcaffd61cb587a4dbdde6c",
"country": "ke",
"merchant_payment_code": "63c9377be268e",
"order_number": "1234567",
"status": "PE", // Status is pending.
"status_date": null,
"open_date": "2023-01-01 01:01:01",
"confirm_date": null,
"transfer_date": null,
"amount_br": "100.00",
"amount_ext": "100.00",
"amount_iof": "0.00",
"currency_rate": "1.0000",
"currency_ext": "KES",
"due_date": "2023-01-01 01:06:01",
"instalments": "1",
"payment_type_code": "mpesa", // Mobile network operator.
"pre_approved": false,
"capture_available": null,
},
"status": "SUCCESS"
}At this stage, the payment will appear as pending (PE) in yourEBANX Dashboardchevron_rightCustomer makes payment
Shortly after a successful charge response, your customer will receive a push notification on their mobile device prompting them to enter a PIN to confirm the payment.
Monitor payment for status changes
Notifications
EBANX will send a notification whenever a payment status changes.
Make sure your system is set up to receive notifications from EBANX for any changes in payment status.
Status
After receiving a notification that status has changed, retrieve the payment status.
When a payment is confirmed, the status will change from pending (PE) to confirmed (CO). If the customer does not complete the payment, the status will eventually change to cancelled (CA).
Congratulations!
You have succesfully integrated Mobile Money.
For more information, refer to theDirect API reference guidechevron_right
Resources
Use the following resources when testing in your sandbox environment.
Sample Cards
Click here to view mock card data to validate your payment integration.
API Reference
Click here to access detailed API documentation to integrate efficiently.
Mock Customer Data
Click here to view mock customer data for testing and validating user flows.
Error Codes
Click here to review common error codes to troubleshoot and resolve issues quickly.
Still need help?
We hope this article was helpful. If you still have questions, you can explore the following options:
- Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
- Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.