Generate Token

This API generates the tokens for authenticating your API calls. This is the first API you need to engage within the set of APIs available as all the other APIs require the information from this API to work.

The API works as below:

1. 1. Get the Base-64 encoding of Consumer Key + “:” + Consumer Secret (note the full colon in the encoding and without the quotes)
2. 2. Create a GET request and set an Authentication header with the value as Basic + encoded value from above step e.g. using the Consumer Credentials above, the header will beAuthorization: Basic
3. 3. Send the request to the endpoint https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials. The raw request will look similar to the following :

   GET /oauth/v1/generate?grant_type=client_credentials HTTP/1.1
   Host: sandbox.safaricom.co.ke
   Authorization: Basic U1BMd0xkMnVBM29ub1BSWENKRjZiV3FXR3hOdkE4Qlo6NldPZ2hNQUdUdUVZS2pYMw==
   Content-Type: application/json
   

4. 4. You will get a response in the sample format shown below. This shows your token and how long it will take before it expires.

   {
   	"access_token": "[access_token]",
   	"expires_in": "3599"
   }
   

Once generated, you somehow need to keep track of the timeout period so it does not expire unknowingly. This means you need to either generate a new token for every request you make or keep a timer variable somewhere and keep checking it. That’s up to you. But know that when you get the “Invalid Access Token” error, your Auth token has expired or is not set. Get a new one.

Register URL

The first API we shall look at is the Register URL API under Consumer to Business (C2B) APIs. It is the first half of the C2B API for receiving payment notifications to your paybill. This API enables you to register the callback URLs via which you shall receive payment notifications for payments to your paybill/till number. The URLs are used by the C2B payment simulation API for sending the transaction details to you.

There are two URLs required for RegisterURL API: Validation URL and Confirmation URL. The reason for two of them is due to the nature of C2B API calls. Below is a flowchart of the C2B process:

The process is explained as below:

1. A customer sends a payment request to your paybill from their phone
2. M-Pesa receives the request and validates it internally first
3. M-Pesa then checks if you have enabled External Validation for the paybill receiving the request
4. If External Validation is enabled:
   1. M-Pesa first sends a Validation request to the Validation URL registered in the system (3^rd party) with the payment details.
   2. The 3^rd Party validates the request and sends an appropriate response to M-Pesa. This response must be received within a given time period or M-Pesa marks the endpoint system as unreachable. The response informs M-Pesa to either complete or cancel the payment:
   3. M-Pesa receives the response and processes the transaction accordingly:
   4. If you had chosen to complete the transaction, M-Pesa sends a Confirmation request to your Confirmation URL with the details of the completed transaction. The transaction is then complete. Thus you shall receive two API calls on your system.
   5. If you had chosen to cancel the payment, M-Pesa simply cancels the transaction and no other request is sent. The transaction is then complete
5. If External Validation is disabled, M-Pesa automatically completes the transaction, and if the transaction is a success, M-Pesa sends a Confirmation request to the Confirmation URL registered in the system. This is the only API call you shall receive on your end.
6. If External Validation is enabled, but for some reason M-Pesa could not reach your endpoint to validate the transaction within the stipulated time period (usually < 8 seconds from the moment the request leaves -Pesa), or no response was received by the time M-Pesa terminates the request, it checks on the default action value saved during registration of the URLs. If the default action was set to Completed, M-Pesa automatically completes the transaction and also tries to send a confirmation request to your other endpoint. If the default action was set to Cancelled, M-Pesa simply cancels the transaction and no Confirmation callbacks are sent. The transaction is then complete.
7. If no URLs are registered in the system, M-Pesa automatically completes the request.
8. M-Pesa then sends an SMS notification to both the customer and paybill owner with the results of the transaction as usual.
9. When the external notifications fail to be sent, you can check on the M-Pesa Org portal and cross-check against received callbacks. The portal has all the payments ever made available, whether you received the callback or not. Manual, but necessary once in a while.

For the two URLs, below are some pointers. These will also apply to the Callback URLs we shall use later on in other APIs:

1. – Use publicly available (Internet-accessible) IP addresses or domain names.
2. – Do not use the words MPesa, M-Pesa, Safaricom or any of their variants in either upper or lower cases in your URLs, the system filters these URLs out and blocks them. Of course, any Localhost URL will be refused.
3. – Do not use public URL testers e.g. ngrok, mockbin or requestbin especially on production, they are also usually blocked by the API.

The request structure will be as shown below:

// URL
[POST] https://sandbox.safaricom.co.ke/mpesa/c2b/v1/registerurl

// HEADERS
Host: sandbox.safaricom.co.ke
Authorization: Bearer [access token]
Content-Type: application/json

// BODY
{
	"ShortCode": "601426",
	"ResponseType": "[Cancelled/Completed]",
	"ConfirmationURL": "[confirmation URL]",
	"ValidationURL": "[validation URL]"
}

The other parameters are:

Shortcode

This is your C2B-enabled paybill number/till number, which you expect to receive payment notifications about.

Response Type

This is the default action value that determines what M-Pesa will do in the scenario that your Validation endpoint is unreachable or is unable to respond on time. Only two values are allowed: Completed or Cancelled. Completed means M-Pesa will automatically complete your transaction, whereas Cancelled means M-Pesa will automatically cancel the transaction.

Then a success response will look like the one below:

{
	"ConversationID": "",
	"OriginatorCoversationID": "",
	"ResponseDescription": "success"
}

Anything else other than the above means there is an error, check error description and fix it if it’s your error. I will cover some common errors encountered on the portal later on in a different section as I compile them one by one from the APIs.

Unfortunately, there is no way to check which URLs are currently registered on the system, or whether the URLs were actually registered in the first place. You can only confirm by performing C2B requests and checking if the registered endpoints are hit or not. Otherwise you can get in touch with the support team and enquire which URLs are currently under your paybill on the system

Also, it is good to know the relationship between shortcodes and the URLs. One paybill can only have one pair of URLs under it, but the same pair of URLs can be used by multiple paybill numbers for transaction notifications. That means it will be up to you to differentiate requests for different paybills.

NB: For this API,and the C2B API below, please test using your own test paybill assigned to you. Most probably, by the time you register your URLs with my paybill above, then get down to testing on the C2B section, someone else will have overwritten your URLs with their own URLs. Then you will be left scratching your head as to why “M-Pesa is not calling my endpoints”.

And that’s pretty much it for Register URL API.

C2B API

This API is used to simulate payment requests from clients and to your API. It basically simulates a payment made from the client phone’s STK/SIM Toolkit menu, and enables you to receive the payment requests in real time. It is the second half of the Register URL API covered above, and requires the URLs registered by the previous API to work. Hopefully you have gone through the previous section to understand how the C2B payment process works, as both are tied to each other. If not, please do, I can wait…

Welcome back. Moving on, the basic C2B request looks like the sample below:

// URL
[POST] https://sandbox.safaricom.co.ke/mpesa/c2b/v1/simulate

// HEADERS
Host: sandbox.safaricom.co.ke
Authorization: Bearer [access token]
Content-Type: application/json

// BODY
{
    "ShortCode": "601426",
    "CommandID": "CustomerPayBillOnline",
    "Amount": "100",
    "Msisdn": "254708374149",
    "BillRefNumber": "account"
}

These are explained below:

Shortcode

This is your paybill number/till number, which you expect to receive payments notifications about.

CommandID

This is a transaction type identifier, which Identifies the type of C2B transaction being made. There are two options: CustomerPayBillOnline and CustomerBuyGoodsOnline. CustomerPayBillOnline is used when simulating Pay Bill requests, which the customer does by going to the M-PESA -> Lipa na M-PESA -> Pay Bill option on mobile, and uses a Paybill/Store number. Thus it requires an Account number/Bill reference number for it to be valid. CustomerBuyGoodsOnline is used for Buy Goods simulation, which is when a customer goes to M-PESA -> Lipa na M-PESA -> Buy Goods and Services on their mobile phones and uses a Till number. This does not require a paybill number, and putting one actually causes the request to fail. Beware that you cannot use a Till number with CustomerPayBillOnline command ID and you cannot use a Pay Bill/Store number with CustomerBuyGoodsOnline Command ID. As of now, I can only see the paybill number provided on the portal, there is no Till number, so the CustomerBuyGoodsOnline command ID might not work as expected, and you might not receive callbacks if you use it since the payment might automatically fail on the backend. But am still going to provision for it here.

Msisdn

This is the test phone number of the virtual customer paying to your paybill. Use the one given in your test credentials section (Test MSISDN) to test. Testing using your own phone numbers will not work with this API since the numbers need to be registered on the testbed first. The number should either begin with 07XX or 2547XX (for now). International numbers are not supported.

BillRefNumber

This simulates the account number that a user would have entered when making a Pay Bill request. This parameter is only required for CustomerPayBillOnline transaction type. It is sent as part of the validation and confirmation requests to you (3rd party) to validate and confirm. It has a maximum of 20 characters.

After sending the request, and assuming you have all the correct details, the success response should be the acknowledgement below:

{
	"ConversationID": "AG_20180324_000066530b914eee3f85",
	"OriginatorCoversationID": "25344-885903-1",
	"ResponseDescription": "Accept the service request successfully."
}

The above response shows that your request has been accepted, and will be processed. The two ‘ConversationID’s are unique identifiers of your transaction’s journey on M-Pesa. M-Pesa itself processes transaction in <~8 seconds, thus, adding 1-2 seconds of network delays and communication, it should take no more than 10 seconds for the validation/confirmation request to hit your endpoint. If it is consistently above that, please check for network or processing delays around your system.

For those who have enabled External Validation, you will first receive a validation request on your Validation URL to validate the request. That request will have the structure below:

NB: For those unfamiliar with callbacks, all API callbacks from transactional requests are POST requests, do not expect GET requests for callbacks. Also, the data is not formatted into application/x-www-form-urlencoded format, it is application/json, so do not expect the data in the usual POST fields/variables of your language, read the results directly from the incoming input stream.

[POST] https://yourdomain.co.ke/your/validation/url

// HEADERS
Content-Type: application/json

// BODY
{
    "TransactionType": "",
    "TransID": "LHG31AA5TX",
    "TransTime": "20170816190243",
    "TransAmount": "200.00",
    "BusinessShortCode": "601426",
    "BillRefNumber": "account",
    "InvoiceNumber": "",
    "OrgAccountBalance": "",
    "ThirdPartyTransID": "",
    "MSISDN": "254708374149",
    "FirstName": "John",
    "MiddleName": "",
    "LastName": "Doe"
}

TransID

This is M-Pesa’s unique transaction identifier for your transaction. This can be used for searching for the transaction later on using the Transaction Query API.

TransTime

Simply the time the transaction was completed on M-Pesa in the format YYYYMMddHHmmss (https://en.wikipedia.org/wiki/Date_format_by_country).

TransAmount

The amount transacted by the customer when paying to your paybill/till.

BusinessShortCode

The shortcode to which the customer paid to. This can be used to differentiate payments to different paybills via the same notification URLs.

BillRefNumber

The account number the customer entered on their phone when making the payment. Applicable to PayBill requests.

MSISDN

The phone number from which the payment was made.

FirstName, MiddleName, LastName

The names of the customer under whom the MSISDN above is registered. The First Name and Last Name are usually mandatory. The Middle Name is optional.

After receiving the request, you are supposed to process it and respond to the API call with either an accept or reject response. To accept, you send the below JSON making sure the value of ResultCode is 0 (zero, must be a literal Integer, not a String like “0”), but the value of ResultDesc can be any alphanumeric value.

{
	"ResultCode": 0,
	"ResultDesc": "Accepted"
}

To reject a transaction, you send the same JSON above, but with the value of ResultCode being any integer EXCEPT 0, as shown below

{
	"ResultCode": 1,
	"ResultDesc": "Rejected"
}

So, basically, sending a ResultCode value of 0 means you accept the transaction, and sending anything else rejects the transaction. Values below 0 are not accepted, and also constitute a rejection.

If transaction has been accepted, M-Pesa will complete the transaction and send a Confirmation request to you. This will have the same structure and values as the Validation request JSON above. This also applies for those who have disabled External Validation. You may respond to the Confirmation request with the JSON below. If you cancel the transaction, no Confirmation will be sent to you. Beware that you cannot cancel a transaction after the Confirmation request has been sent to you. Confirmation marks the completion of the transaction on M-Pesa.

	{
		"C2BPaymentConfirmationResult": "Success"
	}

That marks the end of the C2B transaction. If you find out that M-Pesa is not getting to you, or that your systems are not receiving payment notifications, you can always fall back to the M-Pesa Org Portal to confirm the transactions were received and processed as required.