Online Checkout

This is a form of C2B payment however, the payment is initiated from an online website platform and confirmed by a customer via a USSD interaction.

How Does Online Checkout service work?

  1. Customer will shop online and when checking out, will select Lipa Na M-PESA upon which they will be directed to LNM iFrame.
  2. The iframe will show a summary of transaction details (Amount and reference number) and has a field where the customer enters his/her M-PESA registered Number.
  3. The customer then agrees to terms and conditions and selects LNM.
  4. Immediately the customer selects LNM they get a pop notification on their phone. (This is a network initiated Push USSD) service and will override any other service the customer is doing on his or her Phone.
  5. The notification has transactions summary (Amount to be paid, Item being Purchased and Merchant name). The customer needs to ensure that they have unlocked their Keypad in order to notice the Notification.
  6. The pop notification will request the customer to key in his/her Bonga PIN
  7. Once the customer enters correct Bonga PIN, they will receive another Notification requesting them to confirm or cancel the transaction
  8. Upon confirmation, funds will be deducted from the customers’ M-PESA account and transaction completed.
  9. Progress on Transaction process will be shown on the Lipa Na M-PESA frame and confirmation message displayed when it’s completed.

Transaction Flow Diagram

C2B Online Checkout high level transaction flow diagram

C2B Online Checkout high level transaction flow diagram

Developer Guide


Introduction

This guide describes a Web service for integrating the M-Pesa Check out API to a merchant site. The overall scope of this Web service is to provide primitives for application developers to handle checkout process in a simple way.

The C2B API was created to address the submitting of payment requests from merchant checkout without using the IFRAME. A new improved authentication details have been added to improve on security and additional parameters like merchant transaction ID and encrypted parameters are passed. The API is multi-threaded to improve on transaction processing speeds.

The API allows merchant initiate C2B (paybill via web) transactions. The merchant submits authentication details, transaction details, callback url and callback method. After request submission, the merchant receives instant feedback with validity status of their requests. The C2B API handles customer validation and authentication via USSD push. The customer therefore confirms the transaction. If the customer validation fails or declines the transaction, the API makes a callback to merchant. Otherwise the transaction is processed and status is made through a callback.

This process flow makes the following assumptions:

  • The service is an on demand service where the Merchant always initiates the request when there is a payment to be settled.
  • The Merchant already has an account created by the SAG and has been provided with End point URL

Transaction Process Flow

The Merchant captures the payment details and prepares call to the SAG’s endpoint.

The Merchant invokes SAG’s processCheckOut. The SAG validates the request sent and returns a response

Merchant receives the processCheckoutResponse parameters namely TRX_ID, ENC_PARAMS, RETURN_CODE, DESCRIPTION and CUST_MSG (Customer message)

The merchant is supposed to display the CUST_MSG to the customer after which the merchant should invoke SAG’s confirmPaymentRequest interface to confirm the transaction.

The system will push a USSD menu to the customer and prompt the customer to enter their BONGA PIN and any other validation information.

The transaction is processed on M-PESA and a callback is executed after completion of the transaction.

Endpoints

Production: https://safaricom.co.ke/mpesa_online/lnmo_checkout_server.php?wsdl

WSDL: https://safaricom.co.ke/mpesa_online/lnmo_checkout_server.php?wsdl

Operation: process CheckOut

The Merchant makes a SOAP call to the SAG from which the SAG will call the C2B process to complete the transaction on M-Pesa. The request has two parts namely; process CheckOutRequest and CheckOutHeader. CheckOutHeader carries authentication and validation parameters while processCheckOutRequest carry the transaction parameters.

Request parameters: Request Header

Parameter Type Optional Description
MERCHANT_ID xsd:string No Merchant ID:
When SAG registers a merchant, SAG allocates an ID to the  Merchant
PASSWORD xsd:string No SAG issues the passkey to the Merchant for use in authentication which is an encrypted form of Merchant password issued on creation of the merchant account. Password consists of passkey concatenated with MERCHANT_ID and TIMESTAMP using a defined method of encoding and hashing preferably base64 encoding.
REFERENCE_ID xsd:string No Reference to the product/service offered
TIMESTAMP xsd:string No This is the date time as timestamp of the Merchant request processing page. This is used to generate a password.

Request parameters: Request body

Parameter Type Optional Description
MERCHANT_TRANSACTION_ID xsd:string No This is the unique merchant transaction identifier.
MSISDN xsd:string No This is Merchant customer / shopper phone number. It uniquely identifies shopper/ merchant customer.
REFERENCE_ID xsd:string No Reference to the product/service offered
ENC_PARAMS xsd:string Yes These are merchant encrypted figures, values or parameters that belong to them. It may be anything they want to be passed to help in transaction processing, control or pass.
AMOUNT xsd:double No Merchant send the value of the transaction.
CALL_BACK_URL xsd:string No This is the Merchant’s payment notification endpoint URL. This is important to merchant and their customers to notify on transaction status and the request result.
CALL_BACK_METHOD xsd:string No This is the call back method used to send parameters to the Merchant’s payment notification endpoint

Sample request

 

<soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:tns=”tns:ns”>
<soapenv:Header>
<tns:CheckOutHeader>
<MERCHANT_ID>898945</MERCHANT_ID>
<PASSWORD>MmRmNTliMjIzNjJhNmI5ODVhZGU5OTAxYWQ4NDJkZmI2MWE4ODg1ODFhMTQ3ZmZmNTFjMjg4M2UyYWQ5NTU3Yw==</PASSWORD>
<TIMESTAMP>20141128174717</TIMESTAMP>
</tns:CheckOutHeader>
</soapenv:Header>
<soapenv:Body>
<tns:processCheckOutRequest>
<MERCHANT_TRANSACTION_ID>911-000</MERCHANT_TRANSACTION_ID>
<REFERENCE_ID>1112254500</REFERENCE_ID>
<AMOUNT>54</AMOUNT>
<MSISDN>2547204871865</MSISDN>
<!–Optional:–>
<ENC_PARAMS></ENC_PARAMS>
<CALL_BACK_URL>http://172.21.20.215:8080/test</CALL_BACK_URL>
<CALL_BACK_METHOD>xml</CALL_BACK_METHOD>
<TIMESTAMP>20141128174717</TIMESTAMP>
</tns:processCheckOutRequest>
</soapenv:Body>
</soapenv:Envelope>

 Password

The password should have parameters (MERCHANT­_ID, passkey, TIMESTAMP) encoded using base64_encode and hashed using sha256.

Example below shows the order of parameters and how it should be done:

$MERCHANT_ID = MERCHANT_ID

$passkey  =  passkey provided by SAG

$TIMESTAMP = TIMESTAMP at merchants checkout page.

$PASSWORD  = base64_encode(hash(“sha256”, $MERCHANT_ID . $passkey . $TIMESTAMP));

 

Output Message: processCheckOutResponse

Parameter Type Optional Description
ENC_PARAMS xsd:string No These are encrypted parameters that merchant passes and are passed back to the merchant page during callback.
RETURN_CODE xsd:string No Return/Response Code. “00” for Success and “01” for Failed.
DESCRIPTION xsd:string No Transaction Status description
TRX_ID xsd:string No Transaction ID as generated by the system.
CUST_MSG xsd:string No This is a customer message that informs the customer on how to complete the online checkout transaction validation.

Sample response message

<SOAP-ENV:Envelope xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:ns1=”tns:ns”>
<SOAP-ENV:Body>
<ns1:processCheckOutResponse>
<RETURN_CODE>00</RETURN_CODE>
<DESCRIPTION>Success</DESCRIPTION>
<TRX_ID>cce3d32e0159c1e62a9ec45b67676200</TRX_ID>
<ENC_PARAMS/>
<CUST_MSG>To complete this transaction, enter your Bonga PIN on your handset. if you don’t have one dial *126*5# for instructions</CUST_MSG>
</ns1:processCheckOutResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Operation: confirmTransaction

The Merchant makes a SOAP call to the SAG to confirm an online checkout transaction. The request has two parts namely; transactionConfirmRequest and CheckOutHeader. CheckOutHeader carries authentication and validation parameters while transactionConfirmRequest carry the transaction parameters.

Request parameters: Request Header

Parameter Type Optional Description
MERCHANT_ID xsd:string No Merchant ID: When SAG registers a merchant, SAG allocates an ID to the  Merchant
PASSWORD xsd:string No SAG issues the passkey to the Merchant for use in authentication which is an encrypted form of Merchant password issued on creation of the merchant account. Password consists of passkey concatenated with MERCHANT_ID and TIMESTAMP using a defined method of encoding and hashing preferably base64 encoding.
REFERENCE_ID xsd:string No Reference to the product/service offered
TIMESTAMP xsd:string No This is the date time as timestamp of the Merchant request processing page. This is used to generate a password.

Request parameters: Request body

Parameter Type Optional Description
MERCHANT_TRANSACTION_ID xsd:string Yes MERCHANT_TRANSACTION_ID: This is the unique merchant transaction identifier.  NB: If not provided, TRX_ID must be present.
TRX_ID xsd:string Yes This is Merchant customer / shopper phone number. It uniquely identifies shopper/ merchant customer.  NB: If not provided, MERCHANT_TRANSACTION_ID must be present.

Sample request

<soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:tns=”tns:ns”>
<soapenv:Header>
<tns:CheckOutHeader>
<MERCHANT_ID>898945</MERCHANT_ID>
<PASSWORD>MmRmNTliMjIzNjJhNmI5ODVhZGU5OTAxYWQ4NDJkZmI2MWE4ODg1ODFhMTQ3ZmZmNTFjMjg4M2UyYWQ5NTU3Yw==</PASSWORD>
<TIMESTAMP>20141128174717</TIMESTAMP>
</tns:CheckOutHeader>
</soapenv:Header>
<soapenv:Body>
<tns:transactionConfirmRequest>
<!–Optional:–>
<TRX_ID>?</TRX_ID>
<!–Optional:–>
<MERCHANT_TRANSACTION_ID>911-000</MERCHANT_TRANSACTION_ID>
</tns:transactionConfirmRequest>
</soapenv:Body>
</soapenv:Envelope>

Output Message: transactionConfirmResponse

Parameter Type Optional Description
RETURN_CODE xsd:string No Return/Response Code. “00” for Success and “01” for Failed.
DESCRIPTION xsd:string No Transaction Status description
MERCHANT_TRANSACTION_ID xsd:string No This is the unique merchant transaction identifier.
TRX_ID xsd:string No Transaction ID as generated by the system.

Sample response message

<SOAP-ENV:Envelope xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:ns1=”tns:ns”>
<SOAP-ENV:Body>
<ns1:transactionConfirmResponse>
<RETURN_CODE>00</RETURN_CODE>
<DESCRIPTION>Success</DESCRIPTION>
<MERCHANT_TRANSACTION_ID/>
<TRX_ID>5f6af12be0800c4ffabb4cf2608f0808</TRX_ID>
</ns1:transactionConfirmResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

 

Operation: Payment Notification (Merchant Callback)

Upon completion of transaction on M-PESA, the SAG calls back the merchant’s call back URL via HTTP POST, HTTP GET, XML Result Message depending on merchant callback method defined to pass the details and status of the complete transaction. A callback URL, callback method, username and password are defined on merchant registration. This acts as default parameters if the merchant does not specify the callback method and callback URL during request submission.

The following parameters are passed back via the callback HTTP POST, HTTP GET, XML Result Message;

 

Parameter Description
USERNAME (Optional) Username provided by merchant to authenticate the callback request.
PASSWORD (Optional) Password provided by merchant to authenticate the callback request.
MERCHANT _TRANSACTION_ID Merchant Transaction ID as generated by merchant system. This is passed back as passed during the request by merchant.
M-PESA_TRX_DATE M-PESA transaction timestamp in the format YYYY-MM-DD HH24:MI:SS
M-PESA_TRX_ID M-PESA receipt number
AMOUNT Amount effected on M-PESA
TRX_STATUS  Transaction Status. Pending, Success, Failed, Error
RETURN_CODE Return/Response Code. “00” for Success and “01” for Failed.
DESCRIPTION Transaction Status description
TRX_ID Transaction ID as generated by the system
ENC_PARAMS These are encrypted parameters that merchant passes and are passed back to the merchant page during callback.
MSISDN This is the customer’s number who initiated the payment.

After the callback, the merchant can optionally redirect to either a success or fail page depending on the callback response. The merchant is expected to return the callback response to acknowledge receipt of callback through echoing or printing the word ‘ok’ or ‘success’.

Error Codes

RETURN CODE CODE TYPE DESCRIPTION
0 Success Success. The Request has been successfully received or the transaction has successfully completed.
1 Failure  Insufficient Funds on MSISDN account
3 Failure Amount less than the minimum single transfer allowed on the system.
4 Failure  Amount more than the maximum single transfer amount allowed.
5 Failure  Transaction expired in the instance where it wasn’t picked in time for processing.
6 Failure  Transaction could not be confirmed possibly due to confirm operation failure.
8 Failure Balance would rise above the allowed maximum amount.  This happens if the MSISDN has reached its maximum transaction limit for the day.
9 Failure  The store number specified in the transaction could not be found.  This happens if the Merchant Pay bill number was incorrectly captured during registration.
10 Failure  This occurs when the system is unable to resolve the credit account i.e the MSISDN provided isn’t registered on M-PESA
11 Failure This message is returned when the system is unable to complete the transaction.
12 Failure Message returned when if the transaction details are different from original captured request details.
29 Failure  System Downtime message when the system is inaccessible.
30 Failure Returned when the request is missing reference ID
31 Failure Returned when the request amount is Invalid or blank
32 Failure  Returned when the account in the request hasn’t been activated.
33 Failure Returned when the account hasn’t been approved to transact.
34 Failure  Returned when there is a request processing delay.
35 Failure  Response when a duplicate request is detected.
36 Failure  Response given if incorrect credentials are provided in the request
40 Failure Missing parameters
41 Failure MSISDN is in incorrect format
42 Failure Authentication Failed

Sample HTTP GET Callback

http://10.0.0.1?MSISDN=254700000000&MERCHANT_TRANSACTION_ID=FG232FT0&USERNAME=&PASSWORD=&AMOUNT= 100&TRX_STATUS=Success &RETURN_CODE=00&DESCRIPTION=Transaction successful&M-PESA_TRX_DATE=2014-08-01 15:30:00&M-PESA_TRX_ID=FG232FT0&TRX_ID=1448&ENC_PARAMS=XXXXXXXXXXX

Sample HTTP POST (Plain)

MSISDN:254700000000
AMOUNT:100
M-PESA_TRX_DATE:2014-08-01 15:30:00
M-PESA_TRX_ID:FG232FT0
TRX_STATUS:Success
RETURN_CODE:00
DESCRIPTION:Transaction successful
MERCHANT_TRANSACTION_ID:134562
ENC_PARAMS:XXXXXXXXXXX
TRX_ID:1448

Sample XML Result Message

<SOAP-ENV:Envelope xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:ns1=”tns:ns”>
<SOAP-ENV:Body>
<ns1:ResultMsg>
<MSISDN ns1:type=”xsd:string”>254720471865</MSISDN>
<AMOUNT ns1:type=”xsd:string”>54.0</AMOUNT>
<M-PESA_TRX_DATE ns1:type=”xsd:string”>2014-12-01 16:24:06</M-PESA_TRX_DATE>
<M-PESA_TRX_ID ns1:type=”xsd:string”>null</M-PESA_TRX_ID>
<TRX_STATUS ns1:type=”xsd:string”>Success</TRX_STATUS>
<RETURN_CODE ns1:type=”xsd:string”>00</RETURN_CODE>
<DESCRIPTION ns1:type=”xsd:string”>Success</DESCRIPTION>
<MERCHANT_TRANSACTION_ID ns1:type=”xsd:string”>911-000</MERCHANT_TRANSACTION_ID>
<ENC_PARAMS ns1:type=”xsd:string”></ENC_PARAMS>
<TRX_ID ns1:type=”xsd:string”>cce3d32e0159c1e62a9ec45b67676200</TRX_ID>
</ns1:ResultMsg>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

 

Operation: Transaction Status Query

Transaction Query request helps to get the status of the transaction. It requires MERCHANT_TRANSACTION_ID and TRX_ID. Other mandatory parameters are MERCHANT_ID, PASSWORD generated and encrypted as instructed during a normal request and finally timestamp.

N/B

MERCHANT_TRANSACTION_ID is very different from MERCHANT_ID.  MERCHANT_TRANSACTION_ID is the Id of each transaction. A figure generated by merchant to specify a certain transaction. During transaction query the merchant must provide the TRX_ID and optionally provide MERCHANT_TRANSACTION_ID.

Sample request

<soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:tns=”tns:ns”>
<soapenv:Header>
<tns:CheckOutHeader>
<MERCHANT_ID>898945</MERCHANT_ID>
<PASSWORD>MmRmNTliMjIzNjJhNmI5ODVhZGU5OTAxYWQ4NDJkZmI2MWE4ODg1ODFhMTQ3ZmZmNTFjMjg4M2UyYWQ5NTU3Yw==</PASSWORD>
<TIMESTAMP>20141128174717</TIMESTAMP>
</tns:CheckOutHeader>
</soapenv:Header>
<soapenv:Body>
<tns:transactionStatusRequest>
<!–Optional:–>
<TRX_ID>?</TRX_ID>
<!–Optional:–>
<MERCHANT_TRANSACTION_ID>911-100</MERCHANT_TRANSACTION_ID>
</tns:transactionStatusRequest>
</soapenv:Body>
</soapenv:Envelope>

Sample response

<SOAP-ENV:Envelope xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:ns1=”tns:ns”>
<SOAP-ENV:Body>
<ns1:transactionStatusResponse>
<MSISDN>254720471865</MSISDN>
<AMOUNT>54000</AMOUNT>
<M-PESA_TRX_DATE>2014-12-01 16:59:07</M-PESA_TRX_DATE>
<M-PESA_TRX_ID>N/A</M-PESA_TRX_ID>
<TRX_STATUS>Failed</TRX_STATUS>
<RETURN_CODE>01</RETURN_CODE>
<DESCRIPTION>InsufficientFunds</DESCRIPTION>
<MERCHANT_TRANSACTION_ID/>
<ENC_PARAMS/>
<TRX_ID>ddd396509b168297141a747cd2dc1748</TRX_ID>
</ns1:transactionStatusResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>