Accept Mobile Money Payment with APIs
Another way to accept payments is by using our Mobile Money APIs. The comprehensive guide below will walk you through the process of successfully accepting mobile money on Kora using our APIs.
Get started with accepting Mobile money using APIs
We currently only support payments in Kenyan Shillings and Ghanaian Cedis. For Kenya, we support the following wallets; Mpesa, Airtel, and Equitel. While for Ghana we support; MTN Momo and Airtel Tigo. Here are some test mobile money numbers we created to help you simulate different scenarios for mobile money payments as you integrate.
Step 1: Collect payment data required to initiate payment
To charge a customer, you will need to collect the necessary payment information from the customer.
Here are the request parameters.
Parameter | Type | Required | Description |
---|---|---|---|
reference | String | True | A unique reference for the payment. The reference must be at least 8 characters long. |
amount | Number | True | The amount for the charge |
currency | String | True | The currency for the charge |
redirect_url | String | False | A URL to which we can redirect your customer after their payment is complete |
customer | Object | True | The information of the customer you want to charge |
customer.name | String | False | The name of your customer |
customer.email | String | True | The email of your customer |
mobile_money | Object | True | Object holding the mobile money wallet details |
mobile_money.number | String | True | The mobile number of the customer to be charged e.g 254700000000 |
notification_url | String | False | The webhook URL to be called when the transaction is complete. |
merchant_bears_cost | Boolean | False | This sets who bear the fees of the transaction. If it is set to true, the merchant will bear the fee. If it is set to false, the customer will bear the fee. By default, it is false. |
description | String | False | Information/narration about the transaction |
metadata | Object | False | It takes a JSON object with a maximum of 5 fields/keys. Empty JSON objects are not allowed. Each field name has a maximum length of 20 characters. Allowed characters: A-Z, a-z, 0-9, and -. |
After collecting the necessary mobile money payment information from your customer, prepare your data object to look like the example shown below.
{
"amount": 701,
"currency": "GHS",
"reference": "idkMain27105551011",
"description": "Payment for a emilokan",
"notification_url": "https://webhook.site/1c209942-1a66-4cdf-a7ab-78d9cc684ad2",
"redirect_url": "https://webhook.site",
"customer": {
"name": "John Doe",
"email": "[email protected]"
},
"merchant_bears_cost": true,
"mobile_money": {
"number": "254700000000"
}
}
To charge the number make a POST
request with the payload to our charge mobile money endpoint. Ensure to include the relevant country currency.
Endpoint - POST https://api.korapay.com/merchant/api/v1/charges/mobile-money
If the request is successful, you should receive a message with either OTP
or STK_PROMPT
as the auth model.
Sample OTP
Auth Response:
{
"status": true,
"code": "AA001",
"message": "Authorization required",
"data": {
"amount": 701,
"amount_expected": 701,
"currency": "GHS",
"fee": 1.87,
"vat": 0.13,
"auth_model": "OTP",
"transaction_reference": "KPY-PAY-rYF4c5ZWioeb",
"payment_reference": "idkMain27105551021",
"status": "processing",
"narration": "Payment for a emilokan",
"message": "Token generated and sent out successfully",
"mobile_money": {
"number": "+254700000000"
},
"customer": {
"name": "John Doe",
"email": "[email protected]"
}
}
}
Sample STK_PROMPT
Auth Response:
{
"status": true,
"code": "AA001",
"message": "Authorization required",
"data": {
"amount": 10,
"amount_expected": 10,
"currency": "KES",
"fee": 0.25,
"vat": 0.04,
"auth_model": "STK_PROMPT",
"transaction_reference": "KPY-PAY-rYF4c5ZWioeb",
"payment_reference": "KPY-PAY-79lsPQSqHXSz",
"status": "processing",
"narration": "Live Test Link",
"message": "You will receive a pin prompt on your mobile number +25470000000 for GHS 10. Kindly enter your wallet PIN to authorize the payment",
"mobile_money": {
"number": "254700000000"
},
"customer": {
"name": "John Doe",
"email": "[email protected]"
}
}
}
Step 2: Authorize mobile money transaction
The next step is based on the auth model returned in the previous response after initiating the charge. There are 2 ways of authorizing a transaction OTP
and STK_PROMPT
.
Authorizing an OTP transaction
After making the request to charge the number, if the status of the transaction is processing and auth_model is OTP, this means an OTP has been sent to the wallet owner's phone. You would need to collect the OTP in order to authorize the transaction.
Collect the OTP sent to the customer’s phone and make a request to our authorize endpoint with the OTP and the transaction reference.
Endpoint - https://api.korapay.com/merchant/api/v1/charges/mobile-money/authorize
curl --location 'https://api.korapay.com/merchant/api/v1/charges/mobile-money/authorize' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_KORAPAY_SECRET_KEY' \
--data '{
"reference": "KPY-PAY-rYF4c5ZWioeb",
"token": "123456"
}'
-X POST
If the OTP verification is successful, an STK prompt will be sent to the wallet owner's phone for him to enter his PIN.
Sample response
{
"status": true,
"message": "Authorization required",
"data": {
"amount": "10.00",
"amount_expected": "10.00",
"currency": "GHS",
"fee": 1.75,
"vat": 0.12,
"auth_model": "STK_PROMPT",
"transaction_reference": "KPY-PAY-rYF4c5ZWioeb",
"payment_reference": "KPY-PAY-rYF4c5ZWioeb",
"status": "processing",
"message": "You will receive a prompt on mobile number. Kindly enter your wallet PIN to authorize the payment",
"mobile_money": {
"number": "+254700000000"
}
}
}
{
"status": true,
"message": "Authorization required",
"data": {
"amount": "10.00",
"amount_expected": "10.00",
"currency": "GHS",
"fee": 1.75,
"vat": 0.12,
"auth_model": "OTP",
"transaction_reference": "KPY-PAY-rYF4c5ZWioeb",
"payment_reference": "KPY-PAY-rYF4c5ZWioeb",
"status": "processing",
"message": "The OTP you provided is invalid",
"mobile_money": {
"number": "+254700000000"
},
"attempts_left": 2
}
}
Authorizing an STK transaction
After making the request to charge/authorize the number, if the status of the transaction is processing and auth_model is STK, this means an STK has been sent to the wallet owner's phone.
Step 3: Verify Payment
The final step after receiving payment is to ensure that the payment was successful by making a verification request to our verification charge endpoint. The reference here should be your transaction reference.
Here's a sample request and response for verifying a mobile money payment:
curl https://api.korapay.com/merchant/api/v1/charges/:reference
-H "Authorization: Bearer YOUR_KORAPAY_SECRET_KEY"
-X GET
Sample response for a successful transaction:
{
"status": true,
"message": "Charge retrieved successfully",
"data": {
"reference": "KPY-PAY-rYF4c5ZWioeb",
"status": "success",
"amount": "10.00",
"amount_paid": 0,
"fee": 0.29,
"currency": "GHS",
"description": "Payment for a emilokan",
"mobile_money": {
"number": "+254700000000"
},
"customer": {
"name": "John Doe",
"email": "[email protected]"
}
}
}
{
"status": true,
"message": "Charge retrieved successfully",
"data": {
"reference": "KPY-PAY-rYF4c5ZWioeb",
"status": "failed",
"amount": "2000.00",
"amount_paid": 0,
"fee": "180.00",
"currency": "GHS",
"description": "Mobile money payment for a book",
"payment_attempts": [
{
"reference": "KPY-CM-unEr27sJ616S",
"status": "failed",
"channel": "mobile_money",
"message": "The OTP you provided is invalid"
}
],
"mobile_money": {
"number": "+25470000000"
}
}
}
Step 4: Setup Webhook
You can set your application to receive a confirmation via webhooks when a mobile money payment is successful. Please visit Webhooks to see more information about the webhook request body and how to verify and handle the webhook request.
Error Responses
{
"status": false,
"message": "The OTP you provided is invalid",
"data": null
}
{
"status": false,
"message": "Payment has already been completed"
"data": {}
}
Updated about 1 year ago