1 | P a g e

C1 - Public

SAFARICOM PLC

P.O. BOX 66827-00800

WESTLANDS

NAIROBI, KENYA

TEL +254 722 000000

FAX +254 722 00 4202

EXPRESSION OF INTEREST (EOI) – M-PESA INTEGRATIONS THROUGH API’s

Document Release Date: Tuesday 09th October 2018

Last Date for Receipt of Proposals: Monday 29th October 2018 at 17:00 Hours

2 | P a g e

C1 - Public

Table of Contents

1. Introduction .................................................................................................................................. 3

2. Technical Scope ............................................................................................................................ 3

3. Challenges ................................................................................................................................... 12

4. EOI Response Requirements ..................................................................................................... 13

5. Next Steps .................................................................................................................................... 13

6. Responses .................................................................................................................................... 13

7. Note .............................................................................................................................................. 13

3 | P a g e

C1 - Public

1. Introduction

M-PESA has increasingly become a popular payment option in the Kenyan business environment.

In a bid to grow efficiency and ease reconciliations, organizations have core systems that need real time

updating on transactions. Large Organizations usually have vendors who assist with M-PESA

integrations at a fee. However majority of the organization may not be able to afford regular vendor.

Integrators with portfolios on successful integrations.

M-PESA Integration requires a handshake between the third party core systems with the M-PESA system.

The integration ensures real time communication of payments in the third party system with a

corresponding receipt from M-PESA. The different types of integrations include;

(a) C2B

(b) B2B

(c) B2C

(d) M-PESA Xpress

(e) Reversal API

We therefore are seeking partners who can carry out these M-PESA Integrations to our customers

including Government, Parastatals etc.

2. Technical Scope

Safaricom has exposed API endpoints for accessing M-PESA services; we have M-PESA API endpoints

for B2B, B2C, and C2B. Our APIs are built on REST; data entities are represented as HTTP resources

and are accessed using HTTP verbs, majorly GET and POST.

API request parameters and responses - including errors - are encoded in JSON. Our APIs response status

codes and error codes comply with HTTP status codes as defined in RFC 2616. You can invoke our API

endpoints using REST clients like Postman or SoapUI and command line tools like cUrl and Node.js.

The Scope shall include (But not limited to) the below APIs as provided on the Safaricom Daraja

Platform;

2.1 C2B

2.2 B2C

2.3 M-PESA Xpress

2.4 Transaction Status API

2.1. C2B

4 | P a g e

C1 - Public

This API enables Pay bill and Buy Goods merchants to integrate to M-PESA and receive real time

payments notifications.

The C2B Register URL API registers the 3rd party’s confirmation and validation URLs to M-PESA;

which then maps these URLs to the 3rd party short code. Whenever M-PESA receives a transaction on

the short code, M-PESA triggers a validation request against the validation URL and the 3rd party system

responds to M-PESA with a validation response (either a success or an error code). The response

expected is the success code the 3rd party.

M-PESA completes or cancels the transaction depending on the validation response it receives from the

3rd party system. A confirmation request of the transaction is then sent by M-PESA through the

confirmation URL back to the 3rd party which then should respond with a success acknowledging the

confirmation.

The 3rd party resource URLs for both confirmation and validation must be HTTPS in production.

Validation is an optional feature that needs to be activated on M-PESA, the owner of the short code needs

to make this request for activation.

2.1.4. C2B Register URL - Resource URL

5 | P a g e

C1 - Public

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

C2B Register URL - Request Parameters

Parameter Description

ValidationURL Validation URL for the client.

ConfirmationURL Confirmation URL for the client.

ResponseType Default response type for timeout.

ShortCode The short code of the organization.

2.1.2. Register URL - Response Parameters

Parameter Description

ConversationID A unique numeric code generated by the M-PESA system of the

response to a request.

OriginatorConversationID A unique numeric code generated by the M-PESA system of the

request.

ResponseDescription A response message from the M-PESA system accompanying the

response to a request.

2.1.4. C2B Simulate Transaction

C2B Simulate Transaction - Resource URL

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

C2B Simulate Transaction - Request Parameters

Parameter Description

CommandID Unique command for each transaction type.

Amount The amount been transacted.

6 | P a g e

C1 - Public

Parameter Description

MSISDN MSISDN (phone number) sending the transaction, start with country

code without the plus(+) sign.

BillRefNumber Bill Reference Number (Optional).

ShortCode 6 digit M-Pesa Till Number or PayBill Number

2.1.4. C2B Simulate Transaction - Response Parameters

Parameter Description

ConversationID A unique numeric code generated by the M-Pesa system of the response

to a request.

OriginatorConversationID A unique numeric code generated by the M-Pesa system of the request.

ResponseDescription A response message from the M-Pesa system accompanying the

response to a request.

2.2. B2C API

This API enables Business to Customer (B2C) transactions between a company and customers who are

the end-users of its products or services. Use of this API requires a valid and verified B2C M-PESA Short

code.

7 | P a g e

C1 - Public

2.2.1. B2C Resource URL

POST https://sandbox.safaricom.co.ke/mpesa/b2c/v1/paymentrequest

B2C Query Parameters

Parameter Description

InitiatorName This is the credential/username used to authenticate the transaction request.

SecurityCredential Base64 encoded string of the Security Credential, which is encrypted using M-

Pesa public key and validates the transaction on M-Pesa Core system.

CommandID Unique command for each transaction type e.g. SalaryPayment,

BusinessPayment, PromotionPayment

8 | P a g e

C1 - Public

Parameter Description

Amount The amount being transacted

PartyA Organization’s shortcode initiating the transaction.

PartyB Phone number receiving the transaction

Remarks Comments that are sent along with the transaction.

QueueTimeOutURL The timeout end-point that receives a timeout response.

ResultURL The end-point that receives the response of the transaction

Occasion Optional

2.3. Reversal API

This API enables one to reverse a transaction done.

The reversal request format is as below:

// URL

[POST] https://sandbox.safaricom.co.ke/mpesa/reversal/v1/request

// HEADERS

Host: sandbox.safaricom.co.ke

Authorization: Bearer [access token]

Content-Type: application/json

// BODY

{

"Initiator":"apitest361",

"SecurityCredential":"[encrypted password]",

"CommandID":"TransactionReversal",

"TransactionID":"[original trans_id]",

"Amount":"[trans amount]",

"ReceiverParty":"601426",

"RecieverIdentifierType":"4",

"ResultURL":"https://abcgov/api/callback.php",

"QueueTimeOutURL":"https://abcgov/api/callback.php ",

"Remarks":"please",

"Occasion":"work"

9 | P a g e

C1 - Public

}

Important parameters:

TransactionID

This is the MPesa Transaction ID of the transaction which you wish to reverse.

Amount

The amount transacted in that transaction to be reversed, down to the cent.

ReceiverParty

Your Org's shortcode here.

A successful callback will be as shown below:

{

"Result":

{

"ResultType":0,

"ResultCode":0,

"ResultDesc":"The service request has been accepted successfully.",

"OriginatorConversationID":"10819-695089-1",

"ConversationID":"AG_20170727_00004efadacd98a01d15",

"TransactionID":"LGR019G3J2",

"ReferenceData":

{

"ReferenceItem":

{

"Key":"QueueTimeoutURL",

"Value":"https://internalsandbox.safaricom.co.ke/mpesa/reversa

lresults/v1/submit"

}

}

}

}

2.4. M-PESA Xpress API

The Lipa na M-PESA (LNM) API is an API designed to utilize the new feature introduced by Safaricom

known as STK Push. This feature allows the transaction initiation to be moved from the paying

customer's side to the payee Organization's side. This eliminates the hustle of having to remember

business Pay bill numbers and account numbers for customers, and allows them to simply confirm the

current transaction by entering their M-PESA PIN on their mobile phone. This is done via the STK Pop-

up which appears on a customer's phone that prompts them to enter their PIN. For the business, this API

enables them to preset all the correct info in the payment request and greatly reduce chances of wrong

10 | P a g e

C1 - Public

payments being performed to their systems. It is a C2B transaction, but with the initiator being the

organization instead of the customer. Here, the organization has the option of presetting all required

variables in the request before sending the request, thus this API has no Validation-Confirmation process

of its own unlike the previous C2B API (but is still affected by any previous C2B integrations done on the

short code being used in the request, especially Validation/Confirmation). Its process is explained below:

1. The Business sets the data in the request and sends it.

2. The API receives the request and validates it internally first, then sends you an acknowledgement

response.

3. The API then sends an STK Push request to the target customer's mobile phone. The customer's

phone has to be online and unlocked to receive the request.

4. The customer confirms the payment amount via the message displayed on-screen, then either enters

the PIN or cancels the request accordingly.

5. The API receives the customer's response. If the response is a negative, it cancels the transaction and

sends a corresponding callback to the initiating 3rd party via the predefined callback URL in the

initial request, with the info on why the transaction was cancelled. The possible negative responses

could be due to the following scenarios:

o An invalid PIN entered by the customer

o Timeout due to customer not entering the PIN within a given time period (usually 1 min 30

secs)

o The customer's SIM card not having the STK applet on it

o A literal request cancellation by the user on their phone

o Another STK transaction is already underway on the customer's phone (no more than one

request can be processed at the same time on the same phone)

6. If the PIN is correct, it means the customer accepted the request. The API forwards the transaction to

M-PESA.

7. M-PESA automatically processes the request, then sends the response back to the API system which

then forwards it to you via the callback URL specified in your initial request. Here, the callback can

also either be a success or failure, just like a normal C2B transaction.

8. There are no repeat calls for failed callbacks, thus if the API is unable to send the callback to you,

you have the Transaction Status Query API to confirm the status of the request, or also confirm via

the M-PESA Org. porta

// URL

[POST] https://sandbox.safaricom.co.ke/mpesa/stkpush/v1/processrequest

// HEADERS

Host: sandbox.safaricom.co.ke

Authorization: Bearer [access token]

Content-Type: application/json

// BODY

11 | P a g e

C1 - Public

{

"BusinessShortCode": "174379",

"Password":

"MTc0Mzc5YmZiMjc5ZjlhYTliZGJjZjE1OGU5N2RkNzFhNDY3Y2QyZTBjODkzMDU5YjEwZjc4ZT

ZiNzJhZGExZWQyYzkxOTIwMTgwNzA5MDkwOTQx",

"Timestamp": "20180709090941",

"TransactionType": "[Transaction Type]",

"Amount": "10",

"PartyA": "254708374149",

"PartyB": "174379",

"PhoneNumber": "254708374149",

"CallBackURL": "https://abc/callback.php"

"AccountReference": "account",

"TransactionDesc": "test" ,

}

BusinessShortCode

This is the shortcode of the organization initiating the request and expecting the payment.

Password

This is the Base64-encoded value of the concatenation of the Shortcode + LNM Passkey +

Timestamp, e.g. given the test values above, and using a timestamp of 20180709090941, the

encoded password will be

MTc0Mzc5YmZiMjc5ZjlhYTliZGJjZjE1OGU5N2RkNzFhNDY3Y2QyZTBjODkzMDU5YjEw

Zjc4ZTZiNzJhZGExZWQyYzkxOTIwMTgwNzA5MDkwOTQx

Timestamp

This is the same Timestamp used in the encoding above, in the format YYYMMDDHHmmss.

TransactionType

The type of transaction being performed. These are the same values as the C2B command IDs

(CustomerPayBillOnline and CustomerBuyGoodsOnline) and the same rules apply here. For

now, only CustomerPayBillOnline is supported.

Amount

Self-explanatory.

PartyA

The Debit party of the transaction/the party paying out in the transaction, hereby the phone

number of the customer.

PartyB

The credit party of the transaction/the party being paid in the transaction, hereby being the

shortcode of the organization. This is the same value as the Business Shortcode

PhoneNumber

Same as PartyA.

CallBackURL

12 | P a g e

C1 - Public

This is the endpoint where you want the results of the transaction delivered. Same rules for

Register URL API callbacks apply

AccountReference

This is the value the customer would have put as the account number on their phone if they had

performed the transaction via phone.

TransactionDesc

Short description of the transaction. Optional, but element must be present.

After sending a successful transaction, you can expect a response in the below format:

{

"MerchantRequestID": "25353-1377561-4",

"CheckoutRequestID": "ws_CO_26032018185226297",

"ResponseCode": "0",

"ResponseDescription": "Success. Request accepted for processing",

"CustomerMessage": "Success. Request accepted for processing"

}

3. Challenges

With the continued use of M-PESA, collections have become simpler to the consumer who is already

educated on using M-PESA. However the enterprises have had challenges with scaling the payments due

to the following challenges;

1.1 Lack of Tech Savvy staff

The M-PESA systems needs a web portal. The organization cannot log in without installing the M-

PESA certificate as a security measure. This process is tedious and needs a tech savvy team to

implement

1.2 Reconciliation

The organization administrator has log into the M-PESA system to fetch a report manually on excel.

These is where the transactions are pulled and reconciliation done manually with physical receipts as

proof of payment.

1.3 Reporting

This gets harder’s as transactions increase as the file gets heavier. It requires higher bandwidth.

1.4 Validation

Transactions sent through M-PESA

1.5 Reversals

Legacy revenue systems that do not have usable API’s for M-PESA to handshake

13 | P a g e

C1 - Public

1.6 Lack of Integration Partners

M-PESA does not have pre-qualified M-PESA Integrators in such a case where the government has

no integrator and requests Safaricom to assist with Integration.

4. EOI Response Requirements

The EOI proposal/ response should contain the following information:

1. Legal Certification & Registration by relevant regulatory authorities – i.e. Certificate of

incorporation, Single Business Permit, Tax Compliance Certificate, Memorandum and Articles of

Association for the Company, VAT Certificate Of Registration, Official search report Form CR12,

Form of Annual Return of A Company Having a Share Capital, Registration by relevant

body/institution as an approved training institution, Registration by the National Industrial Training

Authority, Certificate of Cover for Professional Indemnity.

2. Details of the Bidder’s physical premises and contact details.

3. A list of 4-6 Key References where the partner has undertaken integration work

4. Commercials – The partner who shows interest in being considered shall provide together with the

detailed proposal, a commercial proposal of the charges for such integration works.

5. Next Steps

• Partners that show an interest to participate in the provision of the above mentioned services shall be

prequalified for the provision of this service in their area(s) of expertise, subject to the provision of

required documentation and demonstrated ability to deliver the scope of works.

• A frame agreement shall be entered with successful partner(s) for provision of integration services to

government, parastatals etc.

• Only partners who meet the minimum technical evaluation criteria will be considered for further

discussion on service provision.

6. Responses

Please submit your responses by 1700 Hrs (EAT) on Friday 29th October 2018 to

RAMAYO@safaricom.co.ke and JOMARI@safaricom.co.ke

7. Note

Safaricom Limited reserves, at its sole discretion, the right to select or reject, either in totality or partially,

any or all proposals made in the context of this EOI. Any such decisions made will be final and no

14 | P a g e

C1 - Public

correspondence will be engaged into, other than for the purpose of informing the bidders of the outcome of

the process.

Safaricom Limited will not enter into an exclusive agreement with any partner(s) for the provision of

integration services.