M-PESA - Business to Client

This enables your application to send money to m-pesa registered phone number across Kenya.

BODY PARAMS

Parameter Data Type Description Required
source object sender account details Y
source.customer_code string sender business code assigned by Pokea Pay Y
source.account_no string sender account number Y
destination object destination account details Y
destination.country_code string the recipient's ISO country code. Y
destination.name string recipient's full name. Y
destination.mobile_number string the recipient's mobile number Y
transfer object the transfer details Y
transfer.reference string the sender's reference number. unique minimum:6 digit string for each transaction Y
transfer.currency string transfer currency type (USD or KES). Y
transfer.amount string the amount. Max per transaction is USD 10,000 or currency equivalent Y
transfer.date string the transfer date ISO 8601 date format 'YYYY-MM-DD' Y
transfer.description string any additional payment details the sender may have. Y
transfer.channel numeric channel unique code. use 234432 for mpesa b2c Y
result_url string this parameter holds the URL to your server to which callback response will be sent. Y

HEADER PARAMS

Parameter Data Type Description Required
Authorization string bearer token used to access the API Y
signature string A SHA-256 signature to proof that this request is coming from the merchant. Build a String of concatenated values of the request fields with the following order: transfer.amount, transfer.currency, transfer.reference, source.account_no. The resulting text is then signed with Private Key and Base64 encoded. Y

200 Success Response Schema

Parameter Data Type Description
code numeric Response code
message string Response message.

Example Request

                                    
curl --location --request POST 'https://here-prod-api-url.com/remittance/momo/mpesa'
--header 'Accept: application/json'
--header 'Content-Type: application/json'
--header 'signature: +/sk8X9sxiqJujTyUF09ISpD+O4VzrbP7DU8WM3cXJqsX+zqKhA=='
--header 'Authorization: Bearer OEdjeGYQGl7kuvZ8TSD_iXDFy-imh6Myg-cHPCuHhGg'
--data-raw '{
    "source": {
      "customer_code":"XXXXXXXX",
        "account_no":"XXXXX"
    },"destination":{
        "country_code":"KES",
        "name":"John Doe",
        "mobile_number":"2547XXXXXXXXXXX",
    },"transfer":{
        "reference":"12232",
        "currency":"KES",
        "amount":"100",
        "date":"2020-10-23",
        "description":"Dividend remitting",
        "channel":"234432"
    },
     "result_url":"https://webhook.site/dd12b3f6-5e5b-452e-96ee-63fac3c0e73e"
}'
                                    
                                

Example Response

                                    
{
    "code": 0,
    "success": true,
    "message": "The service request is submitted successfully."
}             
                                

Example Success Transaction on the Return Url Response

                                    
{
  "channel": "234432",
  "reference": "12232",
  "transaction_id": "QLD82TMWJE",
  "currency": "KES",
  "amount": "100",
  "fees": "2",
  "result_code": 0,
  "result_description": "The service request is processed successfully.",
  "hash": "d6e15ccdf590e58ac5ad4f52943fe16c4db8a605034a4565d21a86a886a7c1c4"
}
                                    
                                

Example Failed Transaction on the Return Url Response

                                    
{
  "channel": "234432",
  "result_code": 1032,
  "reference" : "12232"
  "result_description": "Bad Request - Invalid Account number",
  "hash": "b80c6893e1f38cc054d2b33fb6c3f7b65f635f45eed7a9c6747da038f2b52d30"
}