Introduction

Proxy API is a simple, intuitive JSON/REST API built upon the stable and well known G2 SOAP/XML API. It aims to provide stability via the use of as few nuts and bolts as possible, and also provides extra features needed by developers during the on-boarding process. Some new developments have been made to try and make the integration process as smooth as possible. Some of those new developments include:

  • - CommandIDs are not being used as part of the request. Instead, the specific CommandID will be determined by the endpoint URL e.g. for a B2C transaction, the CommandID BusinessPayment will be inferred by the URL ~/b2c/businesspayment, and the CommandID PromotionPayment will be inferred by the URL ~/b2c/promotionpayment
  • - C2B Callback URLs can now be changed on the fly on the portal. No need to write long emails requesting for the same ever again.
  • - All requests and callbacks to the Proxy API are recorded, thus one can follow the chronological order of callbacks from their system using the 3rd party RequestID (OriginatorConversationID) to M-Pesa and back. This will be useful for troubleshooting where a request failed or was terminated.
  • - The RequestID (OriginatorConversationID) is now in the control of the 3rd Party, and directly tied to the third party requests, thus one will actually be able to assign own request IDs to their own API requests and eliminate chances of double transactions for the same API request.

This guide explains how Proxy API works.

Prepaid

Proxy API is a prepaid API. That means for one to use the API in production, they need to purchase API credits for their Apps to be able to send or receive API calls to or from M-Pesa respectively. This is explained in more detail in the Account section below.

Apps

This API seeks to emulate Safaricom Daraja API where possible to make it easier to jump on board and begin using. To begin with, you will create Apps which shall be the central point via which you access the API

One can have a maximum of 50 Apps on their account. Each app can be later tied to a specific Shortcode when moving to Production and that app will be used to control access to the Shortcode. Once assigned, the app assignment to the Shortcode cannot be changed. One can perform the following actions on an App:

An App's status determines if an application can be used to make API calls for outgoing requests, or allow processing of validation and confirmation requests for incoming C2B requests. If an App is disabled, it will not be allowed to make any outgoing API calls, and will not allow incoming API requests to its Shortcode to which it is tied to (including C2B).

An app's credits also determine whether an app can be allowed to make API calls. Having no credits also leads to the above scenarios. Please always ensure you keep your app credits topped up to prevent missing API calls to your system.

The remaining credits for the current app are always returned in the RemainingCredits parameter in the response after you send an API request. You can use that to always get the latest value on the number of remaining credits in realtime. You can also view your remaining credits for each app in the Account section.

For you to be able to either delete an app or modify it, you must first fulfill the following conditions:

  • - To delete an app, all credits allocated to the app must be transferred or used up, and the app must not be assigned to any Shortcode in Production.
  • -To change the current environment where an app will be used, all credits allocated to the app must be used up or transferred to an app of the same environment as the current app

Adding an app

To add an App:

  • - Select the Apps menu on the main menu on the left side of the page, then click on the Add button near the top right of the page.
  • - Set the app name and current environment. The App name must be a minimum of 8 characters and must contain only alphanumeric characters, dashes and spaces. Then click on Save.

    NB: Once set, the app name cannot be modified afterwards.

  • If you want to be able to perform B2B requests using the new App, check the App is a B2B App checkbox before you save. Note that this app will be able to perform only B2B requests.


Once created, the App is automatically assigned a set of credentials: an App key and an App secret. These can be used later on to receive an access token to be able to make API calls to the API. To get the API credentials of an existing app, double click on the app from the apps list, and click on Credentials button on the popup that appears. A JSON file with the credentials of the app should download to the current machine. Please keep the credentials in a safe location.

Modifying/Deleting an app

To modify an existing app:

  • - Select the Apps menu on the main menu on the left side of the page, then double-click on the specific app you want to edit.
  • - Change the parameters as needed on the pop-up that appears, then click on Save to save the details
  • - To delete an app, click on Delete and confirm the action. If the criteria for deleting an app are not satisfied, the respective message will be displayed and the request cancelled.

API Tokens and Onboarding

Proxy API tries to simplify account creation and on-boarding by using available and existing Single Sign-On Providers. As of now, only Google and Microsoft are supported, but requests can be made to add more available Providers and depending on the number of requests for a specific Provider, a case can be made to add the Provider onto the system. This allows us to onboard a client with a single operation only.

NB: Closing an account deletes all info related to the client on the system, including apps, transactions and Shortcodes tied to the user. So always confirm before you perform any such action

Proxy API accounts uses the tokens/credits payment method, whereby each API call to the system is charged a given number of credits to be allowed through. The number of credits charged depends on the Subscription Plan assigned to the client at the moment of Go Live. As of now, the default subscription plan (for all APIs except B2B API) charges 1 credit for every API call, where 1 credit is the equivalent of KES. 1. The B2B API is charged starting at 0.1% of the transaction value. The price per credit will never change, but the credits charged per API call can be modified on request and on fulfilling certain criteria.

The Account section controls the Authorization aspect of the API. One can see and add onto the credits available to each app, and one can see the scopes assigned to their Shortcodes once they go live. One can top up an app

To top up a sandbox app, the process is:

  • Double click on the sandbox app you wish to top up
  • Set the number of credits (up to a maximum of 50)
  • Click on Top-up.

As of now, for automated topups, only M-Pesa top-ups of credits are available for production apps. Thus the maximum amount payable within one transaction for credits is the same as the maximum allowed amount for an M-Pesa C2B transaction. To top up a higher amount, please contact the System Administrator.

To top up a production app:

  • - Double click on the production app you wish to top up.
  • - The system will create a transaction reference and display it to you on a pop-up. It will also show you the expected number of credits to be allocated if the current transaction goes through.
  • - Pay the requested amount to the paybill displayed on the portal on your phone, then click on Confirm.
  • - The system continuously polls the backend to check on the status of the transaction. This lasts up to 30 seconds for every time the Confirm button is clicked. If the request is confirmed, the popup disappears and the respective app is credited with the credits. Otherwise, if the popup is closed before confirmation, the request can be completed by going to the Accounts -> Payments section and double-clicking on the respective transaction to complete it.

Account

Allows one to check and top up their App credits, and view the scopes currently assigned to their production Shortcodes. Each App is assigned the Default Subscription plan that determines how many credits are consumer per API call. The Default Plan is 1 credit/API call for all APIs except B2B API, and for B2B API, the default is 0.1% of the transaction value charged from the Credits, where each Credit is equivalent to KES 1.00.

App Credits section shows how many credits each app has remaining. Actions allowed are:


Topping up Sandbox App:

To top up a Sandbox App:

  • - Select the Account menu on the main menu on the left side of the page, then double-click on the specific App you need to top up.
  • - Enter number of credits you want to top up, to a maximum of 50 credits. Then click on Top-up.

Topping up Production App:

To top up a Production App:

  • - Select the Account menu on the main menu on the left side of the page, then double-click on the specific App you need to top up.
  • - Enter number of credits you want to top up, then click on Top-up.
  • - A new popup window appears, giving you the account number to use for this specific transaction, and the credits expected to be topped up. Send the amount shown to M-PESA Paybill Business Number 135230 (Njeka Contractors and General Suppliers) and the given Account Number. The Account number always begins with the letters API. Once you receive payment confirmation message on your handset, click on the Confirm button to check the invoice status.

Transferring Credits

One can transfer credits between Apps in the API. This can be useful when you want to perform a quick transaction but the respective App has no credits, or when one wants to distribute credits deposited into one App among all Apps (instead of topping up every App separately). You can only transfer the number of credits available in the debit account, and can only transfer to an App in the same environment as the App to be debited. To transfer credits:

  • - Select the Account menu on the main menu on the left side of the page, then click on Transfer Credits at the top right of the page.
  • - Select the Debit App (the app whose credits will be subtracted), and the Credit App (App whose credits will be added onto).
  • - Enter number of credits you want to transfer from Debit App to Credit App, then click on Transfer.

Modifying an app

To modify an existing app:

  • - Select the Apps menu on the main menu on the left side of the page, then double-click on the specific app you want to edit.
  • - Change the parameters as needed on the pop-up that appears, then click on Save to save the details
  • - To delete an app, click on Delete and confirm the action. If the criteria for deleting an app are not satisfied, the respective message will be displayed.

To get the API credentials of an existing app, double click on the app from the apps list, and click on Credentials on the popup page that appears. A JSON file with the credentials of the app should download to the current machine. Please keep the credentials in a safe location.

Scopes

This API has provided the following scopes for use:

  • Oauth
  • C2B Paybill
  • C2B Till
  • B2C
  • B2B
  • Transaction Query
  • Reversal

Scopes are assigned to Shortcodes during the go live process. The assignment is done automatically based on the client's Shortcode and M-Pesa Organization Portal access availability. The decision tree is as shown below:

Decision Tree

Once assigned during Go Live, the client can view a Shortcode's assigned scopes by going to Account -> Scopes tab.

Sandbox

The Sandbox is where you get to test out your API prior to going live. There are 4 APIs to be tested out depending on your use case:

Oauth: for creation and refreshing of Authorization tokens C2B: for testing out C2B Validation/Confirmation callbacks B2C: for testing out B2C requests and callbacks B2B: for testing out B2B requests and callbacks Reversal: testing out reversal of C2B transactions Transaction Query: for querying status of 3rd-party initiated requests

Enables registration of Sandbox callback URLs for C2B. The validation URL will be called during validation requests, and the confirmation URL will be called during Confirmation requests. One can test the callback access using the Test button on the right side of the input fields. The test will send a dummy C2B Validation request to the endpoint and return the HTTP response code received, and time taken to perform the HTTP request. This can be used to test how long Validation requests will take to execute on your end. The dummy C2B Validation request has the below structure:

{
	"TransactionType": "CustomerPayBillValidation",
	"TransactionTime": "20190101235959",
	"TransactionID": "IMJ****RMN",
	"TransactionAmount": 10,
	"BusinessShortcode": "000000",
	"AccountReference": "ref0123456789",
	"SenderMSISDN": "254722000111",
	"SenderFirstName": "John",
	"SenderMiddleName": null,
	"SenderLastName": "Doe"
}

The dummy request will have a randomly generated sample TransactionID for every test request, but all the other values will remain the same.

C2B Transaction Validation Default Action simulates what will happen to a transaction when Proxy API is called by MPesa to forward a request, but is unable to reach you. Cancelled means Proxy API will automatically cancel the transaction after receiving no or partial response within up to 6 seconds. Completed means Proxy API will automatically complete the transaction following the above scenario.

Allow C2B Payment Validation sets whether a C2B payment will be forwarded to the 3rd party system for validation or will simply take the default action set above. If not set, the default action will be executed. Otherwise, the request will be forwarded to the 3rd Party and normal execution flow will occur. This is explained in more details in the C2B section

Oauth

Creates the Access tokens used in making API calls. This works as below:

  • Get the SHA3-256 hash of App Key + ":" + App Secret (note the full colon in the encoding, don't include the quotes) e.g. using a random key 1234567890-abcdefghijklmnopqrstuvwxyz and random secret abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz, the SHA3-256 hash will be calculated as sha3_256("1234567890-abcdefghijklmnopqrstuvwxyz:abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz") giving the result fb94869a5819dfb9677585d00f4a6f7325e5313cbbc6d62bbb0c27ed0b29827e. You can always confirm the value and result using the Utilities section under Sandbox.
  • Create a GET request and set an Authentication header with the value as Basic + [space] + encoded value from above step e.g. using the sample Credentials above, the header will be X-Authorization: Basic fb94869a5819dfb9677585d00f4a6f7325e5313cbbc6d62bbb0c27ed0b29827e. Note: there is no Base64 encoding being done on the result of the above function.
  • Send the request to the endpoint https://api.proxyapi.co.ke/sandbox/mpesa/v1/auth. The raw request will be as follows:

    
    GET /sandbox/mpesa/v1/auth HTTP/1.1
    
    Host: api.proxyapi.co.ke
    X-Authorization: Basic fb94869a5819dfb9677585d00f4a6f7325e5313cbbc6d62bbb0c27ed0b29827e
    Content-Type: application/json
    
  • You shall receive a response in the format shown below, showing your access token and the expiry date in Unix timestamp format. Default expiry time is 1 hour, and subsequent requests for the API key will return the same value until the expiry time is over. Once expired, any subsequent calls to the API using the same key will result in a 403: Unauthorized error.

    {
    	"StatusCode": 200,
    	"ResponseCode": "200",
    	"ResponseDesc": "Success",
    	"ServiceStatus": 0,
    	"Data":
    	{
    		"AccessToken": "fa1378e17e8bebd998c94b959ff81195c5ac8989a44ead3c408d3b7076a4ba59",
    		"Expiry": 1564327581
    	}
    }

C2B Paybill

Simulates C2B Paybill requests (payments from customers to businesses) to the M-Pesa API. The C2B Paybill request is the payment a customer makes by going to 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. The flow on how C2B works can be found in the tutorial available here. The C2B Paybill request has the format shown below:

/ URL
[POST] https://api.proxyapi.co.ke/sandbox/mpesa/v1/c2b/customerpaybill

// HEADERS
Host: api.proxyapi.co.ke
X-Authorization: Bearer da5eabaefca067ec4ae0d19994f4812d2e3542da765423f1d5afe2779db17584

// BODY
{
	"SenderMSISDN": "254796778039",
	"ReceiverShortcode": "999112",
	"Amount": 1,
	"AccountReference": "acc_ref"
}

Note the endpoint for this specific request type. The descriptions of the parameters above are defined below:

SenderMSISDN
The phone number of the paying client. It must be a Kenyan number and begin with '+2547...', '2547...' or '07...' (might change later due to addition of MNO codes in Kenya)
ReceiverShortcode
This is the paybill number which you expect to receive payments notifications about
Amount
The amount being transferred, up to a maximum of KES. 70000 inclusive
AccountReference
This simulates the account number that a user would have entered when making a Pay Bill request. This parameter is only required for C2B PayBill 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 and usually accepts the following character regex: /\w\[\]\-\@\$\^\(\):;\./

After sending the request, and assuming you have all the correct details, the success acknowledgement response should have the following format, with the ResponseCode being "0" (a String) for a success:

{
	"StatusCode": 200,
	"ResponseCode": "0",
	"ResponseDesc": "Accept the service request successfully.",
	"ServiceStatus": 0
}

If there was any error in making the request, the callback will have the same format, but the ResponseCode will NOT be "0", instead it will have another value and the explanation for the error in the ResponseDesc parameter. A sample is shown below:

{
	"StatusCode": 503,
	"ResponseCode": "SVC0001",
	"ResponseDesc": "Internal Server Error",
	"ServiceStatus": 0
}

The StatusCode is the standard HTTP status code showing the status of the request with respect to Proxy API. The ResponseCode can take either of two values: a HTTP status code in String format if the request did not reach M-Pesa or was an invalid request and thus was terminated before reaching M-Pesa; or the M-Pesa ResponseCode if the request reached M-Pesa and was received and an acknowledgement returned e.g. if there was an issue with MPesa, and the proxy was not able to reach M-Pesa, or if the request was deemed invalid and terminated, the ResponseCode will contains a standard 503 HTTP status code as shown below:

{
	"StatusCode": 401,
	"ResponseCode": "401",
	"ResponseDesc": "Invalid Credentials",
	"ServiceStatus": 0
}

If the request was received by M-Pesa, the ResponseCode will then contain the usual response code from M-Pesa with the status of the request in the same format as for the success or failed requests above.

C2B Paybill Validation

Once a request has been sent, M-Pesa will send a validation request to the Proxy, which will be processed and forwarded according to the rules set for each Shortcode in the Shortcodes section. A validation request is dependent on validation being enabled on M-Pesa, thus if you do not receive any validation requests on production, confirm the C2B Shortcode has validation enabled from the M-Pesa team or simply ask for it to be enabled. The rules below assume validation has been enabled on M-Pesa and that M-Pesa is allowed to send validation requests to 3rd parties for the specified Shortcode. For each request...

  • If the user is disabled on the system, the transaction is automatically cancelled.
  • If the app does not have any credits remaining, the transaction is automatically cancelled.
  • If validation is not allowed in Shortcode Settings or Sandbox Settings, depending on the environment, the request is recorded in the system then automatically completed. Disallowing of validation to 3rd Party is translated to mean the 3rd Party wants all payments to go through automatically, even if validation is enabled on M-Pesa end.
  • If validation is allowed...
    • ...and the Validation URL is not set, the transaction is recorded in the system then automatically cancelled
    • ...and the Validation URL is set, the API tries to reach the URL and get the validation response. If a response is received within 6 seconds, it repackages the response into an MPesa validation response and pipes back the response back to MPesa. If the Validation URL is set but unreachable or no response is received within 6 seconds, the transaction is recorded then automatically cancelled by the API.

Once processed, if validation is allowed and the request allowed to be forwarded, a Proxy validation request is sent to the 3rd Party system. The format of the request is as below:

{
		"TransactionType": "CustomerPayBillValidation",
		"TransactionTime": "20190616152507",
		"TransactionID": "NFG46QC4NI",
		"TransactionAmount": 10,
		"BusinessShortcode": "999112",
		"AccountReference": "acc_ref",
		"SenderMSISDN": "254713170997",
		"SenderFirstName": "Pombe",
		"SenderMiddleName": null,
		"SenderLastName": "Magufuli",
		"RemainingCredits": 6
}

The parameter definitions are:

TransactionType
The transaction type and action, in this case CustomerPayBillValidation means its a validation request for a C2B Paybill transaction.
TransactionTime
The time the transaction was completed on M-Pesa in the format YYYYMMddHHmmss (https://en.wikipedia.org/wiki/Date_format_by_country)
TransactionID
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.
TransactionAmount
The amount transacted by the customer when paying to your Shortcode
BusinessShortcode
The specific Shortcode to which the customer paid to.
AccountReference
The account number the customer entered on their phone when making the payment.
SenderMSISDN
The phone number from which the payment was made.
SenderFirstName
The first name of the customer under whom the MSISDN above is registered. The First and Last names are usually mandatory. The Middle Name is optional.
SenderMiddleName
The middle name of the customer under whom the MSISDN above is registered, if available.
SenderLastName
The last name of the customer under whom the MSISDN above is registered, if available.
RemainingCredits
The remaining credits left for the Application under the current shortcode after current API transaction has been completed.

Once the 3rd party has validated the transaction, the 3rd party responds with a standard HTTP Status Code of either 200 or any other status code from the 2XX family to complete a request; or any other error codes (4XX, 5XX) to cancel a request. This will be mapped to the respective MPesa complete or cancel responses respectively.

C2B Paybill Confirmation

C2B Paybill Confirmation occurs once either validation has been successfully completed, or the Shortcode does not have validation enabled, meaning all transactions are automatically completed. Once a request is received, MPesa will send a Confirmation request, which will be forwarded to the 3rd party according to the following rules:

  • If there does not exist a Confirmation URL for the 3rd party set in the system, the API will record the request as a 404 - Not found response in the system. This request can be viewed later in the transaction log.
  • If there exists a Confirmation URL for the 3rd party set in the system, the API wll try to send a Confirmation request to that URL. The 3rd party will then respond with a HTTP 2XX status code within 6 seconds to affirm reception of the request. Otherwise the API will deem the request as failed and record it as such in the system. The request can be viewed later in the transaction log. Both results will be mapped to the respective responses to MPesa.

A C2B Paybill Confirmation request has the below structure:

{
		"TransactionType": "CustomerPayBillConfirmation",
		"TransactionTime": "20190616152503",
		"TransactionID": "NFG36QC4NH",
		"TransactionAmount": 1,
		"BusinessShortcode": "999112",
		"AccountReference": "acc_ref",
		"SenderMSISDN": "254713170997",
		"SenderFirstName": "Pombe",
		"SenderMiddleName": null,
		"SenderLastName": "Magufuli",
		"RemainingCredits": 50
}

The parameters are the same as for the validation request except for TransactionType, which shows the request to be a C2B Paybill Confirmation request

C2B Buy Goods

Simulates C2B Buygoods requests to the M-Pesa API. The C2B Buygoods request is the payment a customer makes by going to M-PESA -> Lipa na M-PESA -> Buy Goods and Services option on mobile, and uses a Till number. The flow on how C2B works can be found in the tutorial available here. The C2B Buygoods request has the format shown below:

/ URL
[POST] https://api.proxyapi.co.ke/sandbox/mpesa/v1/c2b/customerbuygoods

// HEADERS
Host: api.proxyapi.co.ke
X-Authorization: Bearer da5eabaefca067ec4ae0d19994f4812d2e3542da765423f1d5afe2779db17584

// BODY
{
	"SenderMSISDN": "254796778039",
	"ReceiverTill": "9991121",
	"Amount": 1
}

Note the endpoint for this specific request type. The descriptions of the parameters above are:

SenderMSISDN
The phone number of the paying client. It must be a Kenyan number and begin with '2547...' or '07...'
ReceiverTill
This is the till number which you expect to receive payments notifications about
Amount
The amount being transferred, up to a maximum of KES. 70000 inclusive

After sending the request, the success or error acknowledgement response should have the same format as for a C2B Paybill acknowledgement described before.

C2B Buygoods Confirmation

A Buy Goods transaction has no validation, thus one should not expect validation requests on their endpoints. This is due to a Till being simply a collection account, thus no validation is expected. There is only a confirmation request with the details of the transaction sent to the 3rd party. A Buygoods confirmation request from the API has the below structure:

{
		"TransactionType": "CustomerBuyGoodsConfirmation",
		"TransactionTime": "20190616153501",
		"TransactionID": "NFG36QC343",
		"TransactionAmount": 1,
		"BusinessShortcode": "9991121",
		"SenderMSISDN": "254713170997",
		"SenderFirstName": "Pombe",
		"SenderMiddleName": null,
		"SenderLastName": "Magufuli",
		"RemainingCredits": 50
}

The parameters have the same definition as a C2B Paybill Confirmation request defined above, except for TransactionType which shows the transaction type to be a Buygoods confirmation request

B2C

Also known as the Bulk Payment API, the Business to Consumer (B2C) API enables a Business or Organization to pay their customers for a variety of reasons. The most common reasons a business can pay their customer include salary payments, promotion payments (e.g. betting winnings payouts) or normal business payments (e.g. transfers from bank to mobile accounts). Each of these scenarios has their own unique characteristics, but all lie under the B2C API category

To learn more on how B2C works, please check out the B2C section in the tutorial.

NB: Usually, existing clients on Broker (apart from C2B clients) have their own VPN connections to perform API requests with, so on Proxy API, we have added the capability to utilize the API using their own SP credentials. This will involve sending a request to Mpesa VAS team for the addition of the API's IP address(es) onto their SP credentials config on Broker to be able to make API requests via Proxy API. Thus the 3rd Party will be able to make API requests both via their systems and Proxy API. For new API clients, they can fully utilize Proxy API using its own SP credentials, and later on configure their own VPN anytime they wish to use for their own systems.

On Proxy API, there are three allowed B2C Command IDs, and each Command ID is mapped to a specific URL. Thus, to make e.g. a BusinessPayment request, the request is sent to the ~/b2c/businesspayment endpoint. This makes it easier to determine and know how to work with the API following the REST standard as closely as possible.

A sample standard Business Payment B2C Request has the following format:

[POST] https://api.proxyapi.co.ke/sandbox/mpesa/v1/b2c/businesspayment

// HEADERS
X-Authorization: Bearer 7becb0f4f704877e2311e25ba962872ccf0eb779498e9d22b42cab86e6c8f06d

// BODY
{
	"RequestID": "7351306617410682",
	"SPID": "107040",
    "SPPassword": "ZWY1YWViYmE3ZTZmZDI3N2RmOGQzMzY4NDE3ZmIxODRmNDZkMDljZWMyYzBkNjk4NGUzZjhhMWE1NmI3NmIzYg==",
    "ServiceID": "107040000",
    "Timestamp": "20170623114011",
	"SenderShortcode": "999112",
	"ReceiverMSISDN": "254796778039",
	"Amount": 10,
	"InitiatorUsername": "testapi",
	"InitiatorEncryptedPassword": "V2Avw4CSEyQlEQLmMo8kwEPlWC1p4NLXmtRaW5GWTfwj21lKr9kOhhgG3ERlWpX3nobp/ZiqNPHa0iEwdh3ABufnAB6AKclsWzpYoVYXUv2nm0dtbAW0BTx061rlUbadvhN8tQb7HaBh4uy2xsuECR2G+PNDf/NTi8CS0F6J+AuyyJwwoeQr+W/Nk4isFmclIfXQ7z6kuRX9R9wvq1Qgz8bBsVsVvsqj210ITEBMQmzwbutYDVfSxQsptYFbrEJQXv3sm3QHfaquE37lACT1SUXzjhpvL2nLB/A1ubGLYVTVmCaJ8m78jyJ4389twKwqZ1Lr0fVn4NflpKzOxRJbag==",
	"CallbackURL": "https://example.domain.com/callback",
	"ReferenceData": [
    	{
    		"Key": "Value"
    	}
    ]
}

Or for non VPN clients:

[POST] https://api.proxyapi.co.ke/sandbox/mpesa/v1/b2c/businesspayment

// HEADERS
X-Authorization: Bearer 7becb0f4f704877e2311e25ba962872ccf0eb779498e9d22b42cab86e6c8f06d

// BODY
{
	"RequestID": "7351306617410682",
	"SenderShortcode": "999112",
	"ReceiverMSISDN": "254796778039",
	"Amount": 10,
	"InitiatorUsername": "testapi",
	"InitiatorEncryptedPassword": "V2Avw4CSEyQlEQLmMo8kwEPlWC1p4NLXmtRaW5GWTfwj21lKr9kOhhgG3ERlWpX3nobp/ZiqNPHa0iEwdh3ABufnAB6AKclsWzpYoVYXUv2nm0dtbAW0BTx061rlUbadvhN8tQb7HaBh4uy2xsuECR2G+PNDf/NTi8CS0F6J+AuyyJwwoeQr+W/Nk4isFmclIfXQ7z6kuRX9R9wvq1Qgz8bBsVsVvsqj210ITEBMQmzwbutYDVfSxQsptYFbrEJQXv3sm3QHfaquE37lACT1SUXzjhpvL2nLB/A1ubGLYVTVmCaJ8m78jyJ4389twKwqZ1Lr0fVn4NflpKzOxRJbag==",
	"CallbackURL": "https://example.domain.com/callback",
	"ReferenceData": [
    	{
    		"Key1": "Value1"
    	},
		{
    		"Key2": "Value2"
    	}
    ]
}

The parameters are:

RequestID
A unique identifier of the request specific to the 3rd party. This parameter is appended to a hash of the 3rd party's Shortcode to create a reference unique to the 3rd party.
SPID
For existing VPN clients. 3rd Party SPID. Optional
SPPassword
For existing VPN clients. 3rd Party hashed SP Password. Optional
ServiceID
For existing VPN clients. 3rd Party SPID. Optional
Timestamp
For existing VPN clients. The timestamp used in the hashing of the SP Password above in the format YYYYMMddHHmmss. Optional
SenderShortcode
The Shortcode of the organization sending the funds.
ReceiverMSISDN
The MSISDN of the receiver party of the transaction. Should be a valid Safaricom Mobile No.
Amount
The amount being transferred, up to a maximum of KES. 70000 inclusive
InitiatorUsername
The username of the API operator as assigned on the M-Pesa Org Portal by the 3rd Party.
InitiatorEncryptedPassword
The password of the API operator assigned by the 3rd Party and encrypted using the public key certificate provided by MPesa
CallbackURL
This is the callback URL where the results of the transaction will be sent. Please read the tutorial to understand how this is used if you are not familiar with it.
ReferenceData
An optional array of data in object format which the 3rd party would like associated with the current request and returned to them in the callback. The array can hold up to five objects, and each object is limited to 1 property, having a key of less than or equal to 125 characters. Also, each object key should be unique in the array

For existing VPN clients' parameters, all SP parameters must be present if they are to be used.

For each supported Command ID, the respective endpoints are as shown below:

Command ID Sandbox Production
BusinessPayment https://api.proxyapi.co.ke/sandbox/mpesa/v1/b2c/businesspayment https://api.proxyapi.co.ke/mpesa/v1/b2c/businesspayment
SalaryPayment https://api.proxyapi.co.ke/sandbox/mpesa/v1/b2c/salarypayment https://api.proxyapi.co.ke/mpesa/v1/b2c/salarypayment
PromotionPayment https://api.proxyapi.co.ke/sandbox/mpesa/v1/b2c/promotionpayment https://api.proxyapi.co.ke/mpesa/v1/b2c/promotionpayment

Once the request has been sent, an acknowledgement is sent in the format shown below.

{
	"RequestID": "419315161054942",
	"MpesaRequestID": "AG_20190727_000049a4a79eb257c1a4",
	"StatusCode": 200,
	"ResponseCode": "0",
	"ResponseDesc": "Accept the service request successfully.",
	"ServiceStatus": 0,
	"RemainingCredits": 6
}

If there was any problem with the request, and the API or MPesa terminates the request, the format will be as shown below:

{
	"StatusCode": 503,
	"ResponseCode": "15",
	"ResponseDesc": "Duplicate OriginatorConversationID.",
	"ServiceStatus": 0
}

The parameters are:

RequestID
The unique identifier of the request from the 3rd Party. This is only present if the request was accepted successfully by M-Pesa.
MpesaRequestID
A unique ID from MPesa (ConversationID) that tracks the request from beginning to end. This is only present if the request was accepted successfully by M-Pesa.
StatusCode
The API's HTTP status code.
ResponseCode
A code from MPesa giving the status of the request (if available). If not available, the HTTP status coe is instead returned in String format. A "0" response code means the request was accepted. Any other value means the request failed.
ResponseDesc
A short description of the response code given above.
ServiceStatus
Status of the Proxy API. A 0 means the API is up and running. Any other value means the API is not available.
RemainingCredits
The remaining credits left for the Application under the current shortcode after current API transaction has been sent. This is only available when a request has been successfully sent to MPesa for 3rd Party-initiated requests.

Once a request has been submitted and processed, a callback will be received and forwarded to the client. The format of the callback for a successful request will be as below:

{
	"ResultCode": 0,
	"ResultDesc": "The service request is processed successfully.",
	"RequestID": "1560676855",
	"MpesaRequestID": "AG_20190616_000068281cafb1773a99",
	"MpesaTransactionID": "NFG16QC1WT",
	"ResultData":
	{
		"TransactionAmount": 20,
		"ReceiverPartyName": "254713170997 - Pombe Magufuli",
		"IsReceiverRegistered": "Y",
		"UtilityAccBalance": 1.0223207E7,
		"WorkingAccBalance": 5745441,
		"TransactionCompleteTime": "16.06.2019 12:15:48"
	},
	"ReferenceData":
	[
		{
			"Key1": "Value 1",
			"Key2": "Value 2"
		}
	]
}

If there was an error during the processing of the request, a failed request callback will be sent, and the format for the callback will be as below

{
	"ResultCode": "2001",
	"ResultDesc": "The initiator information is invalid.",
	"RequestID": "419315161054942",
	"MpesaRequestID": "AG_20190727_000049a4a79eb257c1a4",
	"MpesaTransactionID": "NGR9HBCJ19",
	"ReferenceData":
	[
		{
			"Key1": "Value 1",
			"Key2": "Value 2"
		}
	]
}

The difference between the two being the absence of the ResultData element if the request has failed. The parameters are:

ResultCode
Digit String value showing the current status of the request. A "0" means the request was successful, any other value means the request failed.
ResultDesc
Short description of the response code above
RequestID
3rd Party Unique identifier of the original request.
MpesaRequestID
MPesa's Unique identifier of the original request.
MpesaTransactionID
Globally unique identifier of the completed transaction within MPesa.

All the above parameters will always be present in every callback for all API requests whose initial requests were initiated from the 3rd party (that's you). The ResultData element is special in that it holds the specific data tied to the current request. It is only available for a successful completion of an action/transaction.

ResultData
The inner elements for a successful B2C transaction are:
  • TransactionAmount: The amount transacted during the transaction.
  • ReceiverPartyName: The MSISDN and name of the recipient combined.
  • IsReceiverRegistered: whether the receiver was registered in MPesa at the time the transaction was executed.
  • UtilityAccBalance: The balance of the Utility Account of the initiating Shortcode as at the end of the transaction.
  • WorkingAccBalance: The balance of the Working Account of the initiating Shortcode as at the end of the transaction.
  • TransactionCompleteTime: The time the transaction was completed in the system.
ReferenceData
The initial data attached to the original request. Note how the array elements have been squeezed into one Object.

B2B

The Business to Business (B2B) API enables a Business or Organization to pay other businesses using MPesa or transfer cash between their own separate or other paybills.

To learn more on how B2B works, please check out the B2B section in the tutorial.

The B2B API requires a separate app to perform the request. This app is created as outlined in the Adding an App section above.

On Proxy API, there are three allowed B2B Command IDs, and each Command ID is mapped to a specific URL. This makes it easier to determine and know how to work with the API following the REST standard as closely as possible.

A sample standard B2B Request has the following format:

[POST] https://api.proxyapi.co.ke/sandbox/mpesa/v1/b2b/businesspaybill

// HEADERS
X-Authorization: Bearer 7becb0f4f704877e2311e25ba962872ccf0eb779498e9d22b42cab86e6c8f06d

// BODY
{
    "RequestID": "{{$timestamp}}",
    "SPID": "107031",
    "SPPassword": "Y2Y3M2I2NDgzZTVkNmZlZDQ1MDY0MWY0MDBhYzY5MTgxNDJiNDJlZjI3ODY0ODFjYzQwMGZkYWY1NmQ1MzIwMA==",
    "ServiceID": "107031000",
    "Timestamp": "20190101235959",
    "SenderShortcode": "107039",
    "ReceiverShortcode": "999112",
    "Amount": 1500,
    "AccountReference": "acc_ref",
    "InitiatorUsername": "testapi",
    "InitiatorEncryptedPassword": "EkXOoZzJKbElqemQHdwnINCRZG0w0BfWcYqREq3XsSdNrLBza3eFHR7byNNmJ3HSkfpX/IOIxrVOIo5PflJ5tq4BM33p6bxfDFJ9OrMyBcI/dgR3NyqIiAimVRrmIWaxRMNC3UMltr7yO5CvEvk2sZstnarvaYMxekKYNkli8aSgNCYF9j6EF1Ju8usZbBMfRyTG2gN+oludeUpRHBhiBiMu7itR8gLcqfWERhYZ3kSSqUnxYAzwcOtGu+KCr/sz3DFWNwOzU4Z7VACu7PZ/Ye8wfNGUyOPjYUbG/fRNJ0MGfh7NOfAAJwUdYDJecVclQhJ5mRY92BLf5V29Jp7Xzg==",
    "CallbackURL": "https://example.domain.com/callback",
    "ReferenceData":
    [
    	{
    		"Key": "Value"
    	}
    ]
}

Or for non VPN clients:

[POST] https://api.proxyapi.co.ke/sandbox/mpesa/v1/b2b/businesspaybill

// HEADERS
X-Authorization: Bearer 7becb0f4f704877e2311e25ba962872ccf0eb779498e9d22b42cab86e6c8f06d

// BODY
{
    "RequestID": "{{$timestamp}}",
    "SenderShortcode": "107039",
    "ReceiverShortcode": "999112",
    "Amount": 1500,
    "AccountReference": "acc_ref",
    "InitiatorUsername": "testapi",
    "InitiatorEncryptedPassword": "EkXOoZzJKbElqemQHdwnINCRZG0w0BfWcYqREq3XsSdNrLBza3eFHR7byNNmJ3HSkfpX/IOIxrVOIo5PflJ5tq4BM33p6bxfDFJ9OrMyBcI/dgR3NyqIiAimVRrmIWaxRMNC3UMltr7yO5CvEvk2sZstnarvaYMxekKYNkli8aSgNCYF9j6EF1Ju8usZbBMfRyTG2gN+oludeUpRHBhiBiMu7itR8gLcqfWERhYZ3kSSqUnxYAzwcOtGu+KCr/sz3DFWNwOzU4Z7VACu7PZ/Ye8wfNGUyOPjYUbG/fRNJ0MGfh7NOfAAJwUdYDJecVclQhJ5mRY92BLf5V29Jp7Xzg==",
    "CallbackURL": "https://example.domain.com/callback",
    "ReferenceData":
    [
    	{
    		"Key": "Value"
    	}
    ]
}

The parameters are the same as B2C parameters. The new parameters are described below:

ReceiverShortcode
The shortcode of the receiver party of the transaction. Should be a valid Safaricom Paybill/B2C Shortcode for Business Paybill or Business to Business Transfer, or a valid Safaricom Till for Business BuyGoods.
AccountReference
This is a parameter specific to the Business PayBill API, and is similar to the C2B Account Reference parameter, except that it applies to Businesses. The other two APIs do not need this parameter.

For existing VPN clients' parameters, all SP parameters must be present if they are to be used.

For each supported Command ID, the respective endpoints are as shown below:

Command ID Sandbox Production
BusinessPayBill https://api.proxyapi.co.ke/sandbox/mpesa/v1/b2b/businesspaybill https://api.proxyapi.co.ke/mpesa/v1/b2b/businesspaybill
BusinessBuyGoods https://api.proxyapi.co.ke/sandbox/mpesa/v1/b2b/businessbuygoods https://api.proxyapi.co.ke/mpesa/v1/b2b/businessbuygoods
BusinessToBusinessTransfer https://api.proxyapi.co.ke/sandbox/mpesa/v1/b2b/businesstobusiness https://api.proxyapi.co.ke/mpesa/v1/b2b/businesstobusiness

Once the request has been sent, an acknowledgement is sent in the format shown below.

{
	"RequestID": "419315161054942",
	"MpesaRequestID": "AG_20190727_000049a4a79eb257c1a4",
	"StatusCode": 200,
	"ResponseCode": "0",
	"ResponseDesc": "Accept the service request successfully.",
	"ServiceStatus": 0,
	"RemainingCredits": 7.5
}

If there was any problem with the request, and the API or MPesa terminates the request, the format will be as shown below:

{
	"StatusCode": 503,
	"ResponseCode": "15",
	"ResponseDesc": "Duplicate OriginatorConversationID.",
	"ServiceStatus": 0
}

The parameters are the same as the B2C parameters described before.

Once a request has been submitted and processed, a callback will be received and forwarded to the client. The format of the callback for a successful request will be as below:

{
	"ResultCode": "0",
	"ResultDesc": "The service request is processed successfully.",
	"RequestID": "1567964133",
	"MpesaRequestID": "AG_20190908_00006360f11d96becd48",
	"MpesaTransactionID": "NI87HBHOJJ",
	"ResultData":
	{
		"TransactionAmount": 1500,
		"ReceiverPartyName": "999112 - Peter Test Shortcode",
		"DebitAccBalance": 610012,
		"TransactionCompleteTime": "20190908203346"
	},
	"ReferenceData":
	{
		"BillReferenceNumber": "acc_ref",
		"Key": "Value"
	}
}

Note how the Account Reference is returned as part of the ReferenceData object specifically for a Business Paybill request under the name BillReferenceNumber. If there was an error during the processing of the request, a failed request callback will be sent, and the format for the callback will be as below

{
	"ResultCode": "2001",
	"ResultDesc": "The initiator information is invalid.",
	"RequestID": "419315161054942",
	"MpesaRequestID": "AG_20190727_000049a4a79eb257c1a4",
	"MpesaTransactionID": "NGR9HBCJ19",
	"ReferenceData":
	[
		{
			"Key1": "Value 1",
			"Key2": "Value 2"
		}
	]
}

The difference between the two being the absence of the ResultData element if the request has failed. The parameters are the same as the B2C parameters described before except for the ResultData parameters, which are described below.

ResultData
The inner elements for a successful B2B transaction are:
  • TransactionAmount: The amount transacted during the transaction.
  • ReceiverPartyName: The Shortcode and name of the business which received the funds.
  • DebitAccBalance: The balance of the Account which was debited of the initiating Shortcode as at the end of the transaction. The account debited depends on the API (command ID) used.
  • TransactionCompleteTime: The time the transaction was completed in the system.

Reversal

The Reversal API enables a Business or Organization to reverse transactions received by error or mistake into their C2B accounts. One can only reverse C2B transactions that have been received into their own C2B Shortcodes. Thus, only C2B clients can be assigned access to the Reversal API scope.

To learn more on how Reversal works, please check out the Reversal section in the tutorial.

A sample standard Reversal Request has the following format:

[POST] https://api.proxyapi.co.ke/sandbox/mpesa/v1/reversal

// HEADERS
X-Authorization: Bearer 7becb0f4f704877e2311e25ba962872ccf0eb779498e9d22b42cab86e6c8f06d

// BODY
{
	"RequestID": "2417563671386226",
	"SPID": "107040",
    "SPPassword": "ZWY1YWViYmE3ZTZmZDI3N2RmOGQzMzY4NDE3ZmIxODRmNDZkMDljZWMyYzBkNjk4NGUzZjhhMWE1NmI3NmIzYg==",
    "ServiceID": "107040000",
    "Timestamp": "20170623114011",
	"OriginalTransactionID": "NGR8HBCJ0Y",
	"Shortcode": "999112",
	"InitiatorUsername": "testapi",
	"InitiatorEncryptedPassword": "[encrypted password]",
	"CallbackURL": "http://example.domain.com/callback"
}

Or for non VPN clients:

[POST] https://api.proxyapi.co.ke/sandbox/mpesa/v1/reversal

// HEADERS
X-Authorization: Bearer 7becb0f4f704877e2311e25ba962872ccf0eb779498e9d22b42cab86e6c8f06d

// BODY
{
	"RequestID": "2417563671386226",
	"OriginalTransactionID": "NGR8HBCJ0Y",
	"Shortcode": "999112",
	"InitiatorUsername": "testapi",
	"InitiatorEncryptedPassword": "[encrypted password]",
	"CallbackURL": "http://example.domain.com/callback"
}

The parameters are:

RequestID
A unique identifier of the request specific to the 3rd party. This parameter is appended to a hash of the 3rd party's Shortcode to create a reference unique to the 3rd party.
SPID
For existing VPN clients. 3rd Party SPID. Optional
SPPassword
For existing VPN clients. 3rd Party hashed SP Password. Optional
ServiceID
For existing VPN clients. 3rd Party SPID. Optional
Timestamp
For existing VPN clients. The timestamp used in the hashing of the SP Password above in the format YYYYMMddHHmmss. Optional
OriginalTransactionID
The transaction ID of the C2B transaction to be reversed.
Shortcode
The Shortcode of the receiving organization trying to reverse the transaction.
InitiatorUsername
The username of the API operator as assigned on the M-Pesa Org Portal by the 3rd Party.
InitiatorEncryptedPassword
The password of the API operator assigned by the 3rd Party and encrypted using the public key certificate provided by MPesa
CallbackURL
The callback URL where the results of the transaction will be sent.
ReferenceData
An optional array of data in object format which the 3rd party would like associated with the current request and returned to them in the callback. The array can hold up to five objects, and each object is limited to 1 property, having a key of less than or equal to 125 characters. Also, each object key should be unique in the array

For existing VPN clients' parameters, all must be present if they are to be used.

Once the request has been sent, an acknowledgement is sent in the format shown below. Note how the acknowledgements all share the same format.

{
	"RequestID": "455750110110306",
	"MpesaRequestID": "AG_20190728_00004024e0050253fec3",
	"StatusCode": 200,
	"ResponseCode": "0",
	"ResponseDesc": "Accept the service request successfully.",
	"ServiceStatus": 0,
	"RemainingCredits": 7.5
}

If there was any problem with the request, and the API or MPesa terminates the request, the format will be as shown below:

{
	"StatusCode": 503,
	"ResponseCode": "15",
	"ResponseDesc": "Duplicate OriginatorConversationID.",
	"ServiceStatus": 0
}

The parameters are as explain in the B2C section above.

Once a request has been submitted and processed, a callback will be received and forwarded to the client. The format of the callback for a successful request will be as below:

{
	"ResultCode": "0",
	"ResultDesc": "The service request is processed successfully.",
	"RequestID": "5111472807369880",
	"MpesaRequestID": "AG_20190728_000059a4dc7b99a91fc6",
	"MpesaTransactionID": "NGS5HBCJAL",
	"ResultData":
	{
		"TransactionAmount": "10.00",
		"TransactionCharge": "0.00",
		"CreditPartyName": "254796778039 - Peter Test",
		"DebitPartyName": 999112,
		"TransactionCompleteTime": "20190728085345"
	},
	"ReferenceData": []
}

If there was an error during the processing of the request, a failed request callback will be sent, and the format for the callback will be as below

{
	"ResultCode": "2001",
	"ResultDesc": "The initiator information is invalid.",
	"RequestID": "6840837476710556",
	"MpesaRequestID": "AG_20190728_00005db1aa617ead16ba",
	"MpesaTransactionID": "NGS4HBCJAK",
	"ReferenceData": []
}

For extra info, if the transaction had already been reversed, the expected callback will be as below:

{
	"ResultCode": "R000001",
	"ResultDesc": "The transaction has already been reversed.",
	"RequestID": "5350296948124188",
	"MpesaRequestID": "AG_20190728_0000683cba2713d49f90",
	"MpesaTransactionID": "NGS0000000",
	"ReferenceData": []
}

Note the generic transaction ID for this type of error. This indicates the transaction could not be assigned its own unique transaction ID. The extra specific parameters for a successful reversal are:

TransactionAmount
The amount that was transacted during the request and is to be reversed in this request.
TransactionCharge
The charge applied during the transaction, usually charged to the debit party.
CreditPartyName
The credit party/receiver of the amount after reversal has been completed.
DebitPartyName
The debit party for the reversal who shall be debited the above amount.
TransactionCompleteTime
The time the reversal transaction was completed.
ReferenceData
The initial data attached to the original request. Note how the array elements have been squeezed into one Object.

Transaction Query

The Transaction API enables a Business or Organization to query transactions and their status from MPesa. One can query a transaction based on either the MPesa Transaction ID or the 3rd Party Request ID (OriginatorConversationID) for 3rd-party initiated requests.

A standard Transaction Query Request using the MPesa Transaction ID has the following format:

[POST] https://api.proxyapi.co.ke/sandbox/mpesa/v1/transactionquery/transactionid

// HEADERS
X-Authorization: Bearer f48cefb8c36d07f18554da22e0ac587d0d9e374a07f5fc579cb15f494afba200

// BODY
{
	"RequestID": "2417563671386226",
	"SPID": "107040",
    "SPPassword": "ZWY1YWViYmE3ZTZmZDI3N2RmOGQzMzY4NDE3ZmIxODRmNDZkMDljZWMyYzBkNjk4NGUzZjhhMWE1NmI3NmIzYg==",
    "ServiceID": "107040000",
    "Timestamp": "20170623114011",
	"QueryTransactionID": "NGS7HBCJAN",
	"Shortcode": "999112",
	"InitiatorUsername": "testapi",
	"InitiatorEncryptedPassword": "[encrypted password]",
	"CallbackURL": "http://example.domain.com/callback"
}

Or for non VPN clients:

[POST] https://api.proxyapi.co.ke/sandbox/mpesa/v1/transactionquery/transactionid

// HEADERS
X-Authorization: Bearer f48cefb8c36d07f18554da22e0ac587d0d9e374a07f5fc579cb15f494afba200

// BODY
{
	"RequestID": "2417563671386226",
	"QueryTransactionID": "NGS7HBCJAN",
	"Shortcode": "999112",
	"InitiatorUsername": "testapi",
	"InitiatorEncryptedPassword": "[encrypted password]",
	"CallbackURL": "http://example.domain.com/callback"
}

For querying using the request ID, the format is the same except for the endpoint URL and the query parameter.

https://api.proxyapi.co.ke/sandbox/mpesa/v1/transactionquery/requestid

// HEADERS
X-Authorization: Bearer f48cefb8c36d07f18554da22e0ac587d0d9e374a07f5fc579cb15f494afba200

// BODY
{
	"RequestID": "2417563671386226",
	"SPID": "107040",
    "SPPassword": "ZWY1YWViYmE3ZTZmZDI3N2RmOGQzMzY4NDE3ZmIxODRmNDZkMDljZWMyYzBkNjk4NGUzZjhhMWE1NmI3NmIzYg==",
    "ServiceID": "107040000",
    "Timestamp": "20170623114011",
	"QueryRequestID": "3415694472581614",
	"Shortcode": "999112",
	"InitiatorUsername": "testapi",
	"InitiatorEncryptedPassword": "[encrypted password]",
	"CallbackURL": "http://example.domain.com/callback"
}

The new parameters are:

QueryRequestID
The request ID of the original transaction being queried.
QueryTransactionID
The MPesa transaction ID of the original transaction being queried.

Once the request has been sent, an acknowledgement is sent in the format shown below. Note how the acknowledgements for all APIs share the same format.

{
	"RequestID": "2018896566326572",
	"MpesaRequestID": "AG_20190728_0000539ee0368ae20bec",
	"StatusCode": 200,
	"ResponseCode": "0",
	"ResponseDesc": "Accept the service request successfully.",
	"ServiceStatus": 0,
	"RemainingCredits": 7.5
}

The format for an error acknowledgement is the same as the other APIs.
Once a request has been submitted and processed, a callback will be received and forwarded to the client. The format of the callback for a successful request will be as below:

{
	"ResultCode": "0",
	"ResultDesc": "The service request is processed successfully.",
	"RequestID": "4361455347430956",
	"MpesaRequestID": "AG_20190728_00006661fc3c50049d23",
	"MpesaTransactionID": "NGS0000000",
	"ResultData":
	{
		"TransactionRequestID": "3415694472581614",
		"TransactionID": "NGS7HBCJAN",
		"TransactionType": "Business Payment to Customer via API",
		"TransactionAmount": 10,
		"TransactionCreditPartyName": "254796778039 - Peter Test",
		"TransactionDebitPartyName": "999112 - Peter Test Shortcode",
		"TransactionStatus": "Completed",
		"TransactionStartTime": "20190728091017",
		"TransactionCompleteTime": "20190728091017"
	},
	"ReferenceData": []
}

Extra example: the expected successful callback for querying a reversal of a C2B transaction will be as below:

{
	"ResultCode": "0",
	"ResultDesc": "The service request is processed successfully.",
	"RequestID": "4451103425677044",
	"MpesaRequestID": "AG_20190728_0000685c2939caa61d64",
	"MpesaTransactionID": "NGS0000000",
	"ResultData":
	{
		"TransactionRequestID": "6021749668517066",
		"TransactionID": "NGS9HBCJAP",
		"TransactionType": "Pay Utility Reversal",
		"TransactionAmount": 1,
		"TransactionCreditPartyName": "254796778039 - Peter Test",
		"TransactionDebitPartyName": "999112 - Peter Test Shortcode",
		"TransactionStatus": "Completed",
		"TransactionStartTime": "20190728093738",
		"TransactionCompleteTime": "20190728093738"
	},
	"ReferenceData": []
}

...and querying the original C2B transaction that was reversed by the above reversal transaction will return the below callback:

{
	"ResultCode": "0",
	"ResultDesc": "The service request is processed successfully.",
	"RequestID": "1356960165189202",
	"MpesaRequestID": "AG_20190728_0000589f4178ae4533dc",
	"MpesaTransactionID": "NGS0000000",
	"ResultData":
	{
		"TransactionRequestID": null,
		"TransactionID": "NGS8HBCJAO",
		"TransactionType": "Pay Bill Online",
		"TransactionAmount": 1,
		"TransactionCreditPartyName": "999112 - Peter Test Shortcode",
		"TransactionDebitPartyName": "254796778039 - Peter Test",
		"TransactionStatus": "Completed",
		"TransactionStartTime": "20190728093704",
		"TransactionCompleteTime": "20190728093706"
	},
	"ReferenceData": []
}

A failed request callback will have a similar format as the other APIs. Querying for a non-existent transaction will return the following callback:

{
	"ResultCode": "2032",
	"ResultDesc": "The transaction receipt number does not exist.",
	"RequestID": "3223253853436322",
	"MpesaRequestID": "AG_20190728_00007983339b06e6b48b",
	"MpesaTransactionID": "NGS0000000",
	"ReferenceData": []
}

Note the generic transaction ID for the callbacks of transaction query requests. This indicates the transaction could not be assigned its own unique transaction ID. The extra specific parameters for a transaction query are as below:

TransactionRequestID
The original request ID for the transaction being queried. NB: if you query a transaction that has already been reversed, this parameter will be null
TransactionID
The MPesa transaction ID of the transaction being queried.
TransactionType
A short description of the type of transaction for the transaction being queried.
TransactionAmount
The amount that was transacted when the transaction was executed.
TransactionCreditPartyName
The name of the credit party of the above amount during the transaction.
TransactionDebitPartyName
The name of the debit party of the above amount during the transaction.
TransactionStatus
The status of the queried transaction. Can be any of "Completed", "Expired", "Cancelled", "Declined" or others as they are made available.
TransactionStartTime
The time the queried transaction was initiated.
TransactionCompleteTime
The time the queried transaction was completed.

Transactions

This section enables one to view live/production transactions in almost real time as they come in. One can only view the transactions that their Shortcodes have done and only up to the last 100 latest transactions as received by the API.

Shortcodes

The Shortcodes section allows one to add Shortcodes to the system and view/modify added Shortcodes.

Adding a new Shortcode

To add a new Shortcode to the system, the process is as follows:

  • Precheck: Ensure you have at least one Application set aside for Production environment in the Apps section.
  • Click on the Add button at the top right of the Shortcodes section.
  • Click on Start button.
  • On the Shortcode Type prompt which appears, select the type of Shortcode you are adding. Then click on Next.
  • On the Shortcode Number prompt, enter the Shortcode you wish to add, and optionally add a name. The name can only contain alphanumeric characters, spaces, underscores and dashes. The system will then check if it already exists in the backend and inform you if so. Then click on Next.
  • On the Portal Access prompt, choose if you have access to the official MPesa Portal. If not, your Shortcode will have to go through manual verification means to confirm the ownership of your Shortcode. Then click on Next.
  • If you have access to the official Portal, it means you can easily verify ownership of your Shortcode by means of making an API request. On the portal, create an API operator (e.g. with username shortcodegolive) with the Transaction Status query ORG API permission only, then assign them a password. Also, pick a single transaction on the portal under the given Shortcode to be queried during the process. Encrypt the operator password using the Production Operator encryption certificate, and save the result for later. You can use the Utilities on the portal for that.
  • On the Confirm Access prompt on Proxy API, fill in the Initiator Username, encrypted password and Transaction ID to be queried, then click on Validate. The process takes 30 seconds max (if there is an error) or much less if there was no issue. The last error to be encountered will then be shown after the 30 seconds are up and validation did not work. If it worked, you are asked to assign the Shortcode a Production App that will be used to control access to the Shortcode. This app cannot be changed later, so make sure at least you give it a sensible name.

    NB: The Initiator used in this process will be barred from performing any more outgoing API requests once a Shortcode has been added. This is an extra security measure to protect our clients.

  • Then complete the process.

Deleting a Shortcode

To delete a Shortcode you have to get in touch with us directly.

Modifying a Shortcode

To modify a Shortcode, go to the Shortcodes section and double click on the respective Shortcode. A new view appears with the details of the Shortcode. For all Shortcode types, one can set/modify the name of the Shortcode, and change the status of the Shortcode to Active or Disabled. Disabling a Shortcode means it can no longer be used in transaction requests, and if its a C2B Shortcode, all its validation requests will be cancelled.

For C2B Shortcodes, one can set/modify the Validation and Confirmation URLs, and also test reachability using a dummy C2B Validation/Confirmation request same as the testing in the Sandbox section by clicking on the Test button on the right of the input fields. Beware of the consequences of this action on your system before attempting it.

The C2B Callback URLs can be modified anytime, but leaving them blank will cause all C2B Paybill validation requests to fail, and no C2B callbacks to reach your system. So make sure you set these immediately after adding your C2B Shortcode.

Logs

This section enables one to view all API requests, both from testbed and production in almost real time as they come in. The requests are ordered in the same order as received and processed by the API. You can trace a request using the request ID through all paths involved in the execution of the request and track where exactly a request failed. The Status codes of each request are also shown to determine what was the outcome of the request.

Statistics

This is still a W.I.P. It will be a collection of transaction stats collected in the system e.g. failed transactions, completed transactions, total number of transactions e.t.c.

Comments

© Novacom Technologies Ltd. 2019