Developers

Developers

Introduction

Notes

  • RESTful web service
  • HTTP Basic Authentication over SSL
  • Test bed URL: http://52.20.176.4:8090/api/eft
  • This documentation is intended for programmers who are familiar with REST and JSON.

Overview

After a full integration, you will be able to make transfers to mobile money accounts, transfers to bank accounts in Kenya and to paybill and lipa na M-pesa tills. You will also be able to receive Instant Payment Notifications (IPN) whenever your configured paybill numbers/Lipa na M-pesa tills receive a payment in real-time.

Authentication

The client’s public IP address or API account must be whitelisted before access is granted. Logon credentials will also be provided together with the access grant. We shall provide the following test bed information prior to implementation:

  • CompanyID
  • Username
  • Password

Requests must be made using authenticated HTTP POST requests to certain URLs on the website.

Site URIs:

The authentication is HTTP basic auth using the username and password assigned. See https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side

Data Definition

    • Type Enumeration
Value Description
0 Transfer to a bank Account
1 Transfer to a mobile wallet
2 Business to Business e.g. Paybill, Lipa na M-pesa
    • Primary Account Number Enumeration
Value Description
Mobile Phone Number e.g. 254700000000 When type enumeration above is 1
Bank Account Number When type enumeration above is 0
Bill number (e.g. KPLC bill number – 888888, etc.) When type enumeration above is 2

Error Codes

Error Code Error Description
Error 401 Invalid Username and/or Password
Error 403 Missing Mandatory field(s)
Error 404 Invalid URL
Error 412 Wrong Company ID or Duplicate SystemTraceAuditNumber detected
Error 500 Invalid Bank branch code
Error 400 Query transaction with an Id that doesn’t exist
Error 429 Too many requests

Result Codes

Result Code Description
Code 0 Pending
Code 1 Queued
Code 2 Submit Acknowledged (M-Pesa acknowledges receipt)
Code 3 Completed
Code 4 Cached (at M-Pesa)
Code 5 Failed
Code 6 Submitted (to M-Pesa)
Code 7 Rejected

API Methods

Request

API Description
GET api/Request No documentation available.
GET api/Request/{id} No documentation available.
POST api/Request No documentation available.
GET api/Request?id={id} No documentation available.

Checkout

API Description
POST api/Checkout No documentation available.
PUT api/Checkout/{id} No documentation available.
DELETE api/Checkout/{id} No documentation available.
PUT api/Checkout?id={id} No documentation available.
DELETE api/Checkout?id={id} No documentation available.

WeChatCallback

API Description
GET api/WeChatCallback No documentation available.
GET api/WeChatCallback/{id} No documentation available.
POST api/WeChatCallback No documentation available.
GET api/WeChatCallback?id={id} No documentation available.

WeChat

API Description
GET api/WeChat No documentation available.
GET api/WeChat/{id} No documentation available.
POST api/WeChat No documentation available.
PUT api/WeChat/{id} No documentation available.
DELETE api/WeChat/{id} No documentation available.
GET api/WeChat?id={id} No documentation available.
PUT api/WeChat?id={id} No documentation available.
DELETE api/WeChat?id={id} No documentation available.

EFT

API Description
GET api/EFT No documentation available.
GET api/EFT/{id} No documentation available.
GET api/EFT?stan={stan} No documentation available.
POST api/EFT No documentation available.
DELETE api/EFT/{id} No documentation available.
GET api/EFT?id={id} No documentation available.
GET api/EFT/{stan} No documentation available.
DELETE api/EFT?id={id} No documentation available.

BalanceEnquiry

API Description
GET api/BalanceEnquiry/{id} No documentation available.
GET api/BalanceEnquiry?id={id} No documentation available.

Payment Notifications

Overview

This is intended for Third Party Developers who want to receive IPN (Instant Payment Notification) for M-pesa C2B (Customer to Business) transactions.

Receiving a C2B Notification

Note:

  • The end point URL will be provided by the intended user of this documentation.
  • The end point URL MUST be https.
  • The intended user will specify notification content type i.e application/xml or application/json

The following are the fields passed in the IPN message:

Field Data Type Description Format
MSISDN String Customer Mobile Number 254700000000
BusinessShortCode Integer Business short code provide by Safaricom 12345678
InvoiceNumber Varchar Invoice number ABC123
TransID Integer Unique Transaction Identifier hjfgerew
TransAmount Decimal Transaction Amount 1000.0
ThirdPartyTransID String Third Party Transaction ID TX1001
TransTime DateTime Transaction Date time 20140227082020
KYCInfo String Customer’s First, Second and last name XML

Note: If the above POST is successful, the third party should respond with HTTP code 200 and any other meta data they wish to respond with. Sample IPN Messages

    • Content Type: application/json

  {
                            "Id":"86ec9889-f148-4eba-9fc2-044b7accea39",
                            "MSISDN":"MSISDN",
                            "BusinessShortCode":"BusinessShortCode",
                            "InvoiceNumber":"InvoiceNumber",
                            "TransID":"TransID",
                            "TransAmount":"TransAmount",
                            "ThirdPartyTransID":"ThirdPartyTransID",
                            "TransTime":"TransTime",
                            "BillRefNumber":"BillRefNumber",
                            "KYCInfoList":
                                [
                                    {
                                        "KYCName":"FirstName",
                                        "KYCValue":"Foo"
                                    },
                                    {
                                        "KYCName":"MiddleName",
                                        "KYCValue":"Doo"
                                    },
                                    {
                                        "KYCName":"LastName",
                                        "KYCValue":"Bar"
                                    }
                                ]
                          }

    • Content Type: application/xml,
     <?xml version="1.0" encoding="utf-8" ?>
                                <instantpaymentnotification xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" id="C287557F-0A1D-C74F-8CE2-08D2E4F25CAC">
                                    <msisdn>254700000000</msisdn>
                                    <businessshortcode>217879</businessshortcode>
                                    <invoicenumber></invoicenumber>
                                    <transid>JKH878879r7889734R9</transid>
                                    <transamount>50.00</transamount>
                                    <thirdpartytransid></thirdpartytransid>
                                    <transtime>20151106101346</transtime>
                                    <billrefnumber>07000000</billrefnumber>
                                    <kycinfolist>
                                        <kycinfo>
                                            <kycname>[Personal Details][First Name]</kycname>
                                            <kycvalue>FirsName</kycvalue>
                                        </kycinfo>
                                        <kycinfo>
                                            <kycname>[Personal Details][Middle Name]</kycname>
                                            <kycvalue>MiddleName</kycvalue>
                                        </kycinfo>
                                        <kycinfo>
                                            <kycname>[Personal Details][Last Name]</kycname>
                                            <kycvalue>LastName</kycvalue>
                                        </kycinfo>
                                    </kycinfolist>
                                </instantpaymentnotification>  

Validating C2B Transaction

Note:

  • The third party must validate the authenticity of C2B transaction. This can be done by calling API GET method and passing the ID parameter passed in the IPN message.

If the transaction is valid, the API will respond with HTTP code 200 otherwise HTTP code 403.

Below is an example of the GET request, authorization header must be included. /api/eft/8e33f7d8-ddf4-ca7f-c5c4-08d2e679d9v9

Response is as below:-

{
“Type”: 4,
“TypeDesc”: “Consumer to Business”,
“CompanyId”: “00000000-0000-0000-0000-000000000000”,
“CompanyDesc”: Company Description,
“Remarks”: “?”,
“IsDelivered”: false,
“OrderLines”: null
}

B2C

Notes

  • RESTful web service
  • HTTP Basic Authentication over SSL
  • Test bed URL: http://52.20.176.4:8090/api/eft
  • This documentation is intended for programmers who are familiar with REST and JSON.

Overview

After a full integration, you will be able to make transfers to mobile money accounts, transfers to bank accounts in Kenya and to paybill and lipa na M-pesa tills. You will also be able to receive Instant Payment Notifications (IPN) whenever your configured paybill numbers/Lipa na M-pesa tills receive a payment in real-time.

Authentication

The client’s public IP address or API account must be whitelisted before access is granted. Logon credentials will also be provided together with the access grant. We shall provide the following test bed information prior to implementation:

  • CompanyID
  • Username
  • Password

Requests must be made using authenticated HTTP POST requests to certain URLs on the website.

Site URIs:

The authentication is HTTP basic auth using the username and password assigned. See https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side

Data Definition

    • Type Enumeration
Value Description
0 Transfer to a bank Account
1 Transfer to a mobile wallet
2 Business to Business e.g. Paybill, Lipa na M-pesa
    • Primary Account Number Enumeration
Value Description
Mobile Phone Number e.g. 254700000000 When type enumeration above is 1
Bank Account Number When type enumeration above is 0
Bill number (e.g. KPLC bill number – 888888, etc.) When type enumeration above is 2

Error Codes

Error Code Error Description
Error 401 Invalid Username and/or Password
Error 403 Missing Mandatory field(s)
Error 404 Invalid URL
Error 412 Wrong Company ID or Duplicate SystemTraceAuditNumber detected
Error 500 Invalid Bank branch code
Error 400 Query transaction with an Id that doesn’t exist
Error 429 Too many requests

Result Codes

Result Code Description
Code 0 Pending
Code 1 Queued
Code 2 Submit Acknowledged (M-Pesa acknowledges receipt)
Code 3 Completed
Code 4 Cached (at M-Pesa)
Code 5 Failed
Code 6 Submitted (to M-Pesa)
Code 7 Rejected

API Methods

Request

API Description
GET api/Request No documentation available.
GET api/Request/{id} No documentation available.
POST api/Request No documentation available.
GET api/Request?id={id} No documentation available.

Checkout

API Description
POST api/Checkout No documentation available.
PUT api/Checkout/{id} No documentation available.
DELETE api/Checkout/{id} No documentation available.
PUT api/Checkout?id={id} No documentation available.
DELETE api/Checkout?id={id} No documentation available.

WeChatCallback

API Description
GET api/WeChatCallback No documentation available.
GET api/WeChatCallback/{id} No documentation available.
POST api/WeChatCallback No documentation available.
GET api/WeChatCallback?id={id} No documentation available.

WeChat

API Description
GET api/WeChat No documentation available.
GET api/WeChat/{id} No documentation available.
POST api/WeChat No documentation available.
PUT api/WeChat/{id} No documentation available.
DELETE api/WeChat/{id} No documentation available.
GET api/WeChat?id={id} No documentation available.
PUT api/WeChat?id={id} No documentation available.
DELETE api/WeChat?id={id} No documentation available.

EFT

API Description
GET api/EFT No documentation available.
GET api/EFT/{id} No documentation available.
GET api/EFT?stan={stan} No documentation available.
POST api/EFT No documentation available.
DELETE api/EFT/{id} No documentation available.
GET api/EFT?id={id} No documentation available.
GET api/EFT/{stan} No documentation available.
DELETE api/EFT?id={id} No documentation available.

BalanceEnquiry

API Description
GET api/BalanceEnquiry/{id} No documentation available.
GET api/BalanceEnquiry?id={id} No documentation available.

Payment Notifications

Overview

This is intended for Third Party Developers who want to receive IPN (Instant Payment Notification) for M-pesa C2B (Customer to Business) transactions.

Receiving a C2B Notification

Note:

  • The end point URL will be provided by the intended user of this documentation.
  • The end point URL MUST be https.
  • The intended user will specify notification content type i.e application/xml or application/json

The following are the fields passed in the IPN message:

Field Data Type Description Format
MSISDN String Customer Mobile Number 254700000000
BusinessShortCode Integer Business short code provide by Safaricom 12345678
InvoiceNumber Varchar Invoice number ABC123
TransID Integer Unique Transaction Identifier hjfgerew
TransAmount Decimal Transaction Amount 1000.0
ThirdPartyTransID String Third Party Transaction ID TX1001
TransTime DateTime Transaction Date time 20140227082020
KYCInfo String Customer’s First, Second and last name XML

Note: If the above POST is successful, the third party should respond with HTTP code 200 and any other meta data they wish to respond with. Sample IPN Messages

    • Content Type: application/json

{
&amp;amp;quot;Id&amp;amp;quot;:&amp;amp;quot;86ec9889-f148-4eba-9fc2-044b7accea39&amp;amp;quot;,
&amp;amp;quot;MSISDN&amp;amp;quot;:&amp;amp;quot;MSISDN&amp;amp;quot;,
&amp;amp;quot;BusinessShortCode&amp;amp;quot;:&amp;amp;quot;BusinessShortCode&amp;amp;quot;,
&amp;amp;quot;InvoiceNumber&amp;amp;quot;:&amp;amp;quot;InvoiceNumber&amp;amp;quot;,
&amp;amp;quot;TransID&amp;amp;quot;:&amp;amp;quot;TransID&amp;amp;quot;,
&amp;amp;quot;TransAmount&amp;amp;quot;:&amp;amp;quot;TransAmount&amp;amp;quot;,
&amp;amp;quot;ThirdPartyTransID&amp;amp;quot;:&amp;amp;quot;ThirdPartyTransID&amp;amp;quot;,
&amp;amp;quot;TransTime&amp;amp;quot;:&amp;amp;quot;TransTime&amp;amp;quot;,
&amp;amp;quot;BillRefNumber&amp;amp;quot;:&amp;amp;quot;BillRefNumber&amp;amp;quot;,
&amp;amp;quot;KYCInfoList&amp;amp;quot;:
[
{
&amp;amp;quot;KYCName&amp;amp;quot;:&amp;amp;quot;FirstName&amp;amp;quot;,
&amp;amp;quot;KYCValue&amp;amp;quot;:&amp;amp;quot;Foo&amp;amp;quot;
},
{
&amp;amp;quot;KYCName&amp;amp;quot;:&amp;amp;quot;MiddleName&amp;amp;quot;,
&amp;amp;quot;KYCValue&amp;amp;quot;:&amp;amp;quot;Doo&amp;amp;quot;
},
{
&amp;amp;quot;KYCName&amp;amp;quot;:&amp;amp;quot;LastName&amp;amp;quot;,
&amp;amp;quot;KYCValue&amp;amp;quot;:&amp;amp;quot;Bar&amp;amp;quot;
}
]
}

    • Content Type: application/xml,
  &amp;amp;lt;?xml version=&amp;amp;quot;1.0&amp;amp;quot; encoding=&amp;amp;quot;utf-8&amp;amp;quot; ?&amp;amp;gt;
                                &amp;amp;lt;instantpaymentnotification xmlns:xsi=&amp;amp;quot;http://www.w3.org/2001/XMLSchema-instance&amp;amp;quot; xmlns:xsd=&amp;amp;quot;http://www.w3.org/2001/XMLSchema&amp;amp;quot; id=&amp;amp;quot;C287557F-0A1D-C74F-8CE2-08D2E4F25CAC&amp;amp;quot;&amp;amp;gt;
                                    &amp;amp;lt;msisdn&amp;amp;gt;254700000000&amp;amp;lt;/msisdn&amp;amp;gt;
                                    &amp;amp;lt;businessshortcode&amp;amp;gt;217879&amp;amp;lt;/businessshortcode&amp;amp;gt;
                                    &amp;amp;lt;invoicenumber&amp;amp;gt;&amp;amp;lt;/invoicenumber&amp;amp;gt;
                                    &amp;amp;lt;transid&amp;amp;gt;JKH878879r7889734R9&amp;amp;lt;/transid&amp;amp;gt;
                                    &amp;amp;lt;transamount&amp;amp;gt;50.00&amp;amp;lt;/transamount&amp;amp;gt;
                                    &amp;amp;lt;thirdpartytransid&amp;amp;gt;&amp;amp;lt;/thirdpartytransid&amp;amp;gt;
                                    &amp;amp;lt;transtime&amp;amp;gt;20151106101346&amp;amp;lt;/transtime&amp;amp;gt;
                                    &amp;amp;lt;billrefnumber&amp;amp;gt;07000000&amp;amp;lt;/billrefnumber&amp;amp;gt;
                                    &amp;amp;lt;kycinfolist&amp;amp;gt;
                                        &amp;amp;lt;kycinfo&amp;amp;gt;
                                            &amp;amp;lt;kycname&amp;amp;gt;[Personal Details][First Name]&amp;amp;lt;/kycname&amp;amp;gt;
                                            &amp;amp;lt;kycvalue&amp;amp;gt;FirsName&amp;amp;lt;/kycvalue&amp;amp;gt;
                                        &amp;amp;lt;/kycinfo&amp;amp;gt;
                                        &amp;amp;lt;kycinfo&amp;amp;gt;
                                            &amp;amp;lt;kycname&amp;amp;gt;[Personal Details][Middle Name]&amp;amp;lt;/kycname&amp;amp;gt;
                                            &amp;amp;lt;kycvalue&amp;amp;gt;MiddleName&amp;amp;lt;/kycvalue&amp;amp;gt;
                                        &amp;amp;lt;/kycinfo&amp;amp;gt;
                                        &amp;amp;lt;kycinfo&amp;amp;gt;
                                            &amp;amp;lt;kycname&amp;amp;gt;[Personal Details][Last Name]&amp;amp;lt;/kycname&amp;amp;gt;
                                            &amp;amp;lt;kycvalue&amp;amp;gt;LastName&amp;amp;lt;/kycvalue&amp;amp;gt;
                                        &amp;amp;lt;/kycinfo&amp;amp;gt;
                                    &amp;amp;lt;/kycinfolist&amp;amp;gt;
                                &amp;amp;lt;/instantpaymentnotification&amp;amp;gt;

Validating C2B Transaction

Note:

  • The third party must validate the authenticity of C2B transaction. This can be done by calling API GET method and passing the ID parameter passed in the IPN message.

If the transaction is valid, the API will respond with HTTP code 200 otherwise HTTP code 403.

Below is an example of the GET request, authorization header must be included. /api/eft/8e33f7d8-ddf4-ca7f-c5c4-08d2e679d9v9

Response is as below:-

{
“Type”: 4,
“TypeDesc”: “Consumer to Business”,
“CompanyId”: “00000000-0000-0000-0000-000000000000”,
“CompanyDesc”: Company Description,
“Remarks”: “?”,
“IsDelivered”: false,
“OrderLines”: null
}

B2B

Notes

  • RESTful web service
  • HTTP Basic Authentication over SSL
  • Test bed URL: http://52.20.176.4:8090/api/eft
  • This documentation is intended for programmers who are familiar with REST and JSON.

Overview

After a full integration, you will be able to make transfers to mobile money accounts, transfers to bank accounts in Kenya and to paybill and lipa na M-pesa tills. You will also be able to receive Instant Payment Notifications (IPN) whenever your configured paybill numbers/Lipa na M-pesa tills receive a payment in real-time.

Authentication

The client’s public IP address or API account must be whitelisted before access is granted. Logon credentials will also be provided together with the access grant. We shall provide the following test bed information prior to implementation:

  • CompanyID
  • Username
  • Password

Requests must be made using authenticated HTTP POST requests to certain URLs on the website.

Site URIs:

The authentication is HTTP basic auth using the username and password assigned. See https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side

Data Definition

    • Type Enumeration
Value Description
0 Transfer to a bank Account
1 Transfer to a mobile wallet
2 Business to Business e.g. Paybill, Lipa na M-pesa
    • Primary Account Number Enumeration
Value Description
Mobile Phone Number e.g. 254700000000 When type enumeration above is 1
Bank Account Number When type enumeration above is 0
Bill number (e.g. KPLC bill number – 888888, etc.) When type enumeration above is 2

Error Codes

Error Code Error Description
Error 401 Invalid Username and/or Password
Error 403 Missing Mandatory field(s)
Error 404 Invalid URL
Error 412 Wrong Company ID or Duplicate SystemTraceAuditNumber detected
Error 500 Invalid Bank branch code
Error 400 Query transaction with an Id that doesn’t exist
Error 429 Too many requests

Result Codes

Result Code Description
Code 0 Pending
Code 1 Queued
Code 2 Submit Acknowledged (M-Pesa acknowledges receipt)
Code 3 Completed
Code 4 Cached (at M-Pesa)
Code 5 Failed
Code 6 Submitted (to M-Pesa)
Code 7 Rejected

API Methods

Request

API Description
GET api/Request No documentation available.
GET api/Request/{id} No documentation available.
POST api/Request No documentation available.
GET api/Request?id={id} No documentation available.

Checkout

API Description
POST api/Checkout No documentation available.
PUT api/Checkout/{id} No documentation available.
DELETE api/Checkout/{id} No documentation available.
PUT api/Checkout?id={id} No documentation available.
DELETE api/Checkout?id={id} No documentation available.

WeChatCallback

API Description
GET api/WeChatCallback No documentation available.
GET api/WeChatCallback/{id} No documentation available.
POST api/WeChatCallback No documentation available.
GET api/WeChatCallback?id={id} No documentation available.

WeChat

API Description
GET api/WeChat No documentation available.
GET api/WeChat/{id} No documentation available.
POST api/WeChat No documentation available.
PUT api/WeChat/{id} No documentation available.
DELETE api/WeChat/{id} No documentation available.
GET api/WeChat?id={id} No documentation available.
PUT api/WeChat?id={id} No documentation available.
DELETE api/WeChat?id={id} No documentation available.

EFT

API Description
GET api/EFT No documentation available.
GET api/EFT/{id} No documentation available.
GET api/EFT?stan={stan} No documentation available.
POST api/EFT No documentation available.
DELETE api/EFT/{id} No documentation available.
GET api/EFT?id={id} No documentation available.
GET api/EFT/{stan} No documentation available.
DELETE api/EFT?id={id} No documentation available.

BalanceEnquiry

API Description
GET api/BalanceEnquiry/{id} No documentation available.
GET api/BalanceEnquiry?id={id} No documentation available.

Payment Notifications

Overview

This is intended for Third Party Developers who want to receive IPN (Instant Payment Notification) for M-pesa C2B (Customer to Business) transactions.

Receiving a C2B Notification

Note:

  • The end point URL will be provided by the intended user of this documentation.
  • The end point URL MUST be https.
  • The intended user will specify notification content type i.e application/xml or application/json

The following are the fields passed in the IPN message:

Field Data Type Description Format
MSISDN String Customer Mobile Number 254700000000
BusinessShortCode Integer Business short code provide by Safaricom 12345678
InvoiceNumber Varchar Invoice number ABC123
TransID Integer Unique Transaction Identifier hjfgerew
TransAmount Decimal Transaction Amount 1000.0
ThirdPartyTransID String Third Party Transaction ID TX1001
TransTime DateTime Transaction Date time 20140227082020
KYCInfo String Customer’s First, Second and last name XML

Note: If the above POST is successful, the third party should respond with HTTP code 200 and any other meta data they wish to respond with. Sample IPN Messages

    • Content Type: application/json

{
&amp;amp;quot;Id&amp;amp;quot;:&amp;amp;quot;86ec9889-f148-4eba-9fc2-044b7accea39&amp;amp;quot;,
&amp;amp;quot;MSISDN&amp;amp;quot;:&amp;amp;quot;MSISDN&amp;amp;quot;,
&amp;amp;quot;BusinessShortCode&amp;amp;quot;:&amp;amp;quot;BusinessShortCode&amp;amp;quot;,
&amp;amp;quot;InvoiceNumber&amp;amp;quot;:&amp;amp;quot;InvoiceNumber&amp;amp;quot;,
&amp;amp;quot;TransID&amp;amp;quot;:&amp;amp;quot;TransID&amp;amp;quot;,
&amp;amp;quot;TransAmount&amp;amp;quot;:&amp;amp;quot;TransAmount&amp;amp;quot;,
&amp;amp;quot;ThirdPartyTransID&amp;amp;quot;:&amp;amp;quot;ThirdPartyTransID&amp;amp;quot;,
&amp;amp;quot;TransTime&amp;amp;quot;:&amp;amp;quot;TransTime&amp;amp;quot;,
&amp;amp;quot;BillRefNumber&amp;amp;quot;:&amp;amp;quot;BillRefNumber&amp;amp;quot;,
&amp;amp;quot;KYCInfoList&amp;amp;quot;:
[
{
&amp;amp;quot;KYCName&amp;amp;quot;:&amp;amp;quot;FirstName&amp;amp;quot;,
&amp;amp;quot;KYCValue&amp;amp;quot;:&amp;amp;quot;Foo&amp;amp;quot;
},
{
&amp;amp;quot;KYCName&amp;amp;quot;:&amp;amp;quot;MiddleName&amp;amp;quot;,
&amp;amp;quot;KYCValue&amp;amp;quot;:&amp;amp;quot;Doo&amp;amp;quot;
},
{
&amp;amp;quot;KYCName&amp;amp;quot;:&amp;amp;quot;LastName&amp;amp;quot;,
&amp;amp;quot;KYCValue&amp;amp;quot;:&amp;amp;quot;Bar&amp;amp;quot;
}
]
}

    • Content Type: application/xml,
  &amp;amp;lt;?xml version=&amp;amp;quot;1.0&amp;amp;quot; encoding=&amp;amp;quot;utf-8&amp;amp;quot; ?&amp;amp;gt;
                                &amp;amp;lt;instantpaymentnotification xmlns:xsi=&amp;amp;quot;http://www.w3.org/2001/XMLSchema-instance&amp;amp;quot; xmlns:xsd=&amp;amp;quot;http://www.w3.org/2001/XMLSchema&amp;amp;quot; id=&amp;amp;quot;C287557F-0A1D-C74F-8CE2-08D2E4F25CAC&amp;amp;quot;&amp;amp;gt;
                                    &amp;amp;lt;msisdn&amp;amp;gt;254700000000&amp;amp;lt;/msisdn&amp;amp;gt;
                                    &amp;amp;lt;businessshortcode&amp;amp;gt;217879&amp;amp;lt;/businessshortcode&amp;amp;gt;
                                    &amp;amp;lt;invoicenumber&amp;amp;gt;&amp;amp;lt;/invoicenumber&amp;amp;gt;
                                    &amp;amp;lt;transid&amp;amp;gt;JKH878879r7889734R9&amp;amp;lt;/transid&amp;amp;gt;
                                    &amp;amp;lt;transamount&amp;amp;gt;50.00&amp;amp;lt;/transamount&amp;amp;gt;
                                    &amp;amp;lt;thirdpartytransid&amp;amp;gt;&amp;amp;lt;/thirdpartytransid&amp;amp;gt;
                                    &amp;amp;lt;transtime&amp;amp;gt;20151106101346&amp;amp;lt;/transtime&amp;amp;gt;
                                    &amp;amp;lt;billrefnumber&amp;amp;gt;07000000&amp;amp;lt;/billrefnumber&amp;amp;gt;
                                    &amp;amp;lt;kycinfolist&amp;amp;gt;
                                        &amp;amp;lt;kycinfo&amp;amp;gt;
                                            &amp;amp;lt;kycname&amp;amp;gt;[Personal Details][First Name]&amp;amp;lt;/kycname&amp;amp;gt;
                                            &amp;amp;lt;kycvalue&amp;amp;gt;FirsName&amp;amp;lt;/kycvalue&amp;amp;gt;
                                        &amp;amp;lt;/kycinfo&amp;amp;gt;
                                        &amp;amp;lt;kycinfo&amp;amp;gt;
                                            &amp;amp;lt;kycname&amp;amp;gt;[Personal Details][Middle Name]&amp;amp;lt;/kycname&amp;amp;gt;
                                            &amp;amp;lt;kycvalue&amp;amp;gt;MiddleName&amp;amp;lt;/kycvalue&amp;amp;gt;
                                        &amp;amp;lt;/kycinfo&amp;amp;gt;
                                        &amp;amp;lt;kycinfo&amp;amp;gt;
                                            &amp;amp;lt;kycname&amp;amp;gt;[Personal Details][Last Name]&amp;amp;lt;/kycname&amp;amp;gt;
                                            &amp;amp;lt;kycvalue&amp;amp;gt;LastName&amp;amp;lt;/kycvalue&amp;amp;gt;
                                        &amp;amp;lt;/kycinfo&amp;amp;gt;
                                    &amp;amp;lt;/kycinfolist&amp;amp;gt;
                                &amp;amp;lt;/instantpaymentnotification&amp;amp;gt;

Validating C2B Transaction

Note:

  • The third party must validate the authenticity of C2B transaction. This can be done by calling API GET method and passing the ID parameter passed in the IPN message.

If the transaction is valid, the API will respond with HTTP code 200 otherwise HTTP code 403.

Below is an example of the GET request, authorization header must be included. /api/eft/8e33f7d8-ddf4-ca7f-c5c4-08d2e679d9v9

Response is as below:-

{
“Type”: 4,
“TypeDesc”: “Consumer to Business”,
“CompanyId”: “00000000-0000-0000-0000-000000000000”,
“CompanyDesc”: Company Description,
“Remarks”: “?”,
“IsDelivered”: false,
“OrderLines”: null
}

C2B

Notes

  • RESTful web service
  • HTTP Basic Authentication over SSL
  • Test bed URL: http://52.20.176.4:8090/api/eft
  • This documentation is intended for programmers who are familiar with REST and JSON.

Overview

After a full integration, you will be able to make transfers to mobile money accounts, transfers to bank accounts in Kenya and to paybill and lipa na M-pesa tills. You will also be able to receive Instant Payment Notifications (IPN) whenever your configured paybill numbers/Lipa na M-pesa tills receive a payment in real-time.

Authentication

The client’s public IP address or API account must be whitelisted before access is granted. Logon credentials will also be provided together with the access grant. We shall provide the following test bed information prior to implementation:

  • CompanyID
  • Username
  • Password

Requests must be made using authenticated HTTP POST requests to certain URLs on the website.

Site URIs:

The authentication is HTTP basic auth using the username and password assigned. See https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side

Data Definition

    • Type Enumeration
Value Description
0 Transfer to a bank Account
1 Transfer to a mobile wallet
2 Business to Business e.g. Paybill, Lipa na M-pesa
    • Primary Account Number Enumeration
Value Description
Mobile Phone Number e.g. 254700000000 When type enumeration above is 1
Bank Account Number When type enumeration above is 0
Bill number (e.g. KPLC bill number – 888888, etc.) When type enumeration above is 2

Error Codes

Error Code Error Description
Error 401 Invalid Username and/or Password
Error 403 Missing Mandatory field(s)
Error 404 Invalid URL
Error 412 Wrong Company ID or Duplicate SystemTraceAuditNumber detected
Error 500 Invalid Bank branch code
Error 400 Query transaction with an Id that doesn’t exist
Error 429 Too many requests

Result Codes

Result Code Description
Code 0 Pending
Code 1 Queued
Code 2 Submit Acknowledged (M-Pesa acknowledges receipt)
Code 3 Completed
Code 4 Cached (at M-Pesa)
Code 5 Failed
Code 6 Submitted (to M-Pesa)
Code 7 Rejected

API Methods

Request

API Description
GET api/Request No documentation available.
GET api/Request/{id} No documentation available.
POST api/Request No documentation available.
GET api/Request?id={id} No documentation available.

Checkout

API Description
POST api/Checkout No documentation available.
PUT api/Checkout/{id} No documentation available.
DELETE api/Checkout/{id} No documentation available.
PUT api/Checkout?id={id} No documentation available.
DELETE api/Checkout?id={id} No documentation available.

WeChatCallback

API Description
GET api/WeChatCallback No documentation available.
GET api/WeChatCallback/{id} No documentation available.
POST api/WeChatCallback No documentation available.
GET api/WeChatCallback?id={id} No documentation available.

WeChat

API Description
GET api/WeChat No documentation available.
GET api/WeChat/{id} No documentation available.
POST api/WeChat No documentation available.
PUT api/WeChat/{id} No documentation available.
DELETE api/WeChat/{id} No documentation available.
GET api/WeChat?id={id} No documentation available.
PUT api/WeChat?id={id} No documentation available.
DELETE api/WeChat?id={id} No documentation available.

EFT

API Description
GET api/EFT No documentation available.
GET api/EFT/{id} No documentation available.
GET api/EFT?stan={stan} No documentation available.
POST api/EFT No documentation available.
DELETE api/EFT/{id} No documentation available.
GET api/EFT?id={id} No documentation available.
GET api/EFT/{stan} No documentation available.
DELETE api/EFT?id={id} No documentation available.

BalanceEnquiry

API Description
GET api/BalanceEnquiry/{id} No documentation available.
GET api/BalanceEnquiry?id={id} No documentation available.

Payment Notifications

Overview

This is intended for Third Party Developers who want to receive IPN (Instant Payment Notification) for M-pesa C2B (Customer to Business) transactions.

Receiving a C2B Notification

Note:

  • The end point URL will be provided by the intended user of this documentation.
  • The end point URL MUST be https.
  • The intended user will specify notification content type i.e application/xml or application/json

The following are the fields passed in the IPN message:

Field Data Type Description Format
MSISDN String Customer Mobile Number 254700000000
BusinessShortCode Integer Business short code provide by Safaricom 12345678
InvoiceNumber Varchar Invoice number ABC123
TransID Integer Unique Transaction Identifier hjfgerew
TransAmount Decimal Transaction Amount 1000.0
ThirdPartyTransID String Third Party Transaction ID TX1001
TransTime DateTime Transaction Date time 20140227082020
KYCInfo String Customer’s First, Second and last name XML

Note: If the above POST is successful, the third party should respond with HTTP code 200 and any other meta data they wish to respond with. Sample IPN Messages

    • Content Type: application/json

{
&amp;amp;quot;Id&amp;amp;quot;:&amp;amp;quot;86ec9889-f148-4eba-9fc2-044b7accea39&amp;amp;quot;,
&amp;amp;quot;MSISDN&amp;amp;quot;:&amp;amp;quot;MSISDN&amp;amp;quot;,
&amp;amp;quot;BusinessShortCode&amp;amp;quot;:&amp;amp;quot;BusinessShortCode&amp;amp;quot;,
&amp;amp;quot;InvoiceNumber&amp;amp;quot;:&amp;amp;quot;InvoiceNumber&amp;amp;quot;,
&amp;amp;quot;TransID&amp;amp;quot;:&amp;amp;quot;TransID&amp;amp;quot;,
&amp;amp;quot;TransAmount&amp;amp;quot;:&amp;amp;quot;TransAmount&amp;amp;quot;,
&amp;amp;quot;ThirdPartyTransID&amp;amp;quot;:&amp;amp;quot;ThirdPartyTransID&amp;amp;quot;,
&amp;amp;quot;TransTime&amp;amp;quot;:&amp;amp;quot;TransTime&amp;amp;quot;,
&amp;amp;quot;BillRefNumber&amp;amp;quot;:&amp;amp;quot;BillRefNumber&amp;amp;quot;,
&amp;amp;quot;KYCInfoList&amp;amp;quot;:
[
{
&amp;amp;quot;KYCName&amp;amp;quot;:&amp;amp;quot;FirstName&amp;amp;quot;,
&amp;amp;quot;KYCValue&amp;amp;quot;:&amp;amp;quot;Foo&amp;amp;quot;
},
{
&amp;amp;quot;KYCName&amp;amp;quot;:&amp;amp;quot;MiddleName&amp;amp;quot;,
&amp;amp;quot;KYCValue&amp;amp;quot;:&amp;amp;quot;Doo&amp;amp;quot;
},
{
&amp;amp;quot;KYCName&amp;amp;quot;:&amp;amp;quot;LastName&amp;amp;quot;,
&amp;amp;quot;KYCValue&amp;amp;quot;:&amp;amp;quot;Bar&amp;amp;quot;
}
]
}

    • Content Type: application/xml,
  &amp;amp;lt;?xml version=&amp;amp;quot;1.0&amp;amp;quot; encoding=&amp;amp;quot;utf-8&amp;amp;quot; ?&amp;amp;gt;
                                &amp;amp;lt;instantpaymentnotification xmlns:xsi=&amp;amp;quot;http://www.w3.org/2001/XMLSchema-instance&amp;amp;quot; xmlns:xsd=&amp;amp;quot;http://www.w3.org/2001/XMLSchema&amp;amp;quot; id=&amp;amp;quot;C287557F-0A1D-C74F-8CE2-08D2E4F25CAC&amp;amp;quot;&amp;amp;gt;
                                    &amp;amp;lt;msisdn&amp;amp;gt;254700000000&amp;amp;lt;/msisdn&amp;amp;gt;
                                    &amp;amp;lt;businessshortcode&amp;amp;gt;217879&amp;amp;lt;/businessshortcode&amp;amp;gt;
                                    &amp;amp;lt;invoicenumber&amp;amp;gt;&amp;amp;lt;/invoicenumber&amp;amp;gt;
                                    &amp;amp;lt;transid&amp;amp;gt;JKH878879r7889734R9&amp;amp;lt;/transid&amp;amp;gt;
                                    &amp;amp;lt;transamount&amp;amp;gt;50.00&amp;amp;lt;/transamount&amp;amp;gt;
                                    &amp;amp;lt;thirdpartytransid&amp;amp;gt;&amp;amp;lt;/thirdpartytransid&amp;amp;gt;
                                    &amp;amp;lt;transtime&amp;amp;gt;20151106101346&amp;amp;lt;/transtime&amp;amp;gt;
                                    &amp;amp;lt;billrefnumber&amp;amp;gt;07000000&amp;amp;lt;/billrefnumber&amp;amp;gt;
                                    &amp;amp;lt;kycinfolist&amp;amp;gt;
                                        &amp;amp;lt;kycinfo&amp;amp;gt;
                                            &amp;amp;lt;kycname&amp;amp;gt;[Personal Details][First Name]&amp;amp;lt;/kycname&amp;amp;gt;
                                            &amp;amp;lt;kycvalue&amp;amp;gt;FirsName&amp;amp;lt;/kycvalue&amp;amp;gt;
                                        &amp;amp;lt;/kycinfo&amp;amp;gt;
                                        &amp;amp;lt;kycinfo&amp;amp;gt;
                                            &amp;amp;lt;kycname&amp;amp;gt;[Personal Details][Middle Name]&amp;amp;lt;/kycname&amp;amp;gt;
                                            &amp;amp;lt;kycvalue&amp;amp;gt;MiddleName&amp;amp;lt;/kycvalue&amp;amp;gt;
                                        &amp;amp;lt;/kycinfo&amp;amp;gt;
                                        &amp;amp;lt;kycinfo&amp;amp;gt;
                                            &amp;amp;lt;kycname&amp;amp;gt;[Personal Details][Last Name]&amp;amp;lt;/kycname&amp;amp;gt;
                                            &amp;amp;lt;kycvalue&amp;amp;gt;LastName&amp;amp;lt;/kycvalue&amp;amp;gt;
                                        &amp;amp;lt;/kycinfo&amp;amp;gt;
                                    &amp;amp;lt;/kycinfolist&amp;amp;gt;
                                &amp;amp;lt;/instantpaymentnotification&amp;amp;gt;

Validating C2B Transaction

Note:

  • The third party must validate the authenticity of C2B transaction. This can be done by calling API GET method and passing the ID parameter passed in the IPN message.

If the transaction is valid, the API will respond with HTTP code 200 otherwise HTTP code 403.

Below is an example of the GET request, authorization header must be included. /api/eft/8e33f7d8-ddf4-ca7f-c5c4-08d2e679d9v9

Response is as below:-

{
“Type”: 4,
“TypeDesc”: “Consumer to Business”,
“CompanyId”: “00000000-0000-0000-0000-000000000000”,
“CompanyDesc”: Company Description,
“Remarks”: “?”,
“IsDelivered”: false,
“OrderLines”: null
}

Account Transfers

Notes

  • RESTful web service
  • HTTP Basic Authentication over SSL
  • Test bed URL: http://52.20.176.4:8090/api/eft
  • This documentation is intended for programmers who are familiar with REST and JSON.

Overview

After a full integration, you will be able to make transfers to mobile money accounts, transfers to bank accounts in Kenya and to paybill and lipa na M-pesa tills. You will also be able to receive Instant Payment Notifications (IPN) whenever your configured paybill numbers/Lipa na M-pesa tills receive a payment in real-time.

Authentication

The client’s public IP address or API account must be whitelisted before access is granted. Logon credentials will also be provided together with the access grant. We shall provide the following test bed information prior to implementation:

  • CompanyID
  • Username
  • Password

Requests must be made using authenticated HTTP POST requests to certain URLs on the website.

Site URIs:

The authentication is HTTP basic auth using the username and password assigned. See https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side

Data Definition

    • Type Enumeration
Value Description
0 Transfer to a bank Account
1 Transfer to a mobile wallet
2 Business to Business e.g. Paybill, Lipa na M-pesa
    • Primary Account Number Enumeration
Value Description
Mobile Phone Number e.g. 254700000000 When type enumeration above is 1
Bank Account Number When type enumeration above is 0
Bill number (e.g. KPLC bill number – 888888, etc.) When type enumeration above is 2

Error Codes

Error Code Error Description
Error 401 Invalid Username and/or Password
Error 403 Missing Mandatory field(s)
Error 404 Invalid URL
Error 412 Wrong Company ID or Duplicate SystemTraceAuditNumber detected
Error 500 Invalid Bank branch code
Error 400 Query transaction with an Id that doesn’t exist
Error 429 Too many requests

Result Codes

Result Code Description
Code 0 Pending
Code 1 Queued
Code 2 Submit Acknowledged (M-Pesa acknowledges receipt)
Code 3 Completed
Code 4 Cached (at M-Pesa)
Code 5 Failed
Code 6 Submitted (to M-Pesa)
Code 7 Rejected

API Methods

Request

API Description
GET api/Request No documentation available.
GET api/Request/{id} No documentation available.
POST api/Request No documentation available.
GET api/Request?id={id} No documentation available.

Checkout

API Description
POST api/Checkout No documentation available.
PUT api/Checkout/{id} No documentation available.
DELETE api/Checkout/{id} No documentation available.
PUT api/Checkout?id={id} No documentation available.
DELETE api/Checkout?id={id} No documentation available.

WeChatCallback

API Description
GET api/WeChatCallback No documentation available.
GET api/WeChatCallback/{id} No documentation available.
POST api/WeChatCallback No documentation available.
GET api/WeChatCallback?id={id} No documentation available.

WeChat

API Description
GET api/WeChat No documentation available.
GET api/WeChat/{id} No documentation available.
POST api/WeChat No documentation available.
PUT api/WeChat/{id} No documentation available.
DELETE api/WeChat/{id} No documentation available.
GET api/WeChat?id={id} No documentation available.
PUT api/WeChat?id={id} No documentation available.
DELETE api/WeChat?id={id} No documentation available.

EFT

API Description
GET api/EFT No documentation available.
GET api/EFT/{id} No documentation available.
GET api/EFT?stan={stan} No documentation available.
POST api/EFT No documentation available.
DELETE api/EFT/{id} No documentation available.
GET api/EFT?id={id} No documentation available.
GET api/EFT/{stan} No documentation available.
DELETE api/EFT?id={id} No documentation available.

BalanceEnquiry

API Description
GET api/BalanceEnquiry/{id} No documentation available.
GET api/BalanceEnquiry?id={id} No documentation available.

Payment Notifications

Overview

This is intended for Third Party Developers who want to receive IPN (Instant Payment Notification) for M-pesa C2B (Customer to Business) transactions.

Receiving a C2B Notification

Note:

  • The end point URL will be provided by the intended user of this documentation.
  • The end point URL MUST be https.
  • The intended user will specify notification content type i.e application/xml or application/json

The following are the fields passed in the IPN message:

Field Data Type Description Format
MSISDN String Customer Mobile Number 254700000000
BusinessShortCode Integer Business short code provide by Safaricom 12345678
InvoiceNumber Varchar Invoice number ABC123
TransID Integer Unique Transaction Identifier hjfgerew
TransAmount Decimal Transaction Amount 1000.0
ThirdPartyTransID String Third Party Transaction ID TX1001
TransTime DateTime Transaction Date time 20140227082020
KYCInfo String Customer’s First, Second and last name XML

Note: If the above POST is successful, the third party should respond with HTTP code 200 and any other meta data they wish to respond with. Sample IPN Messages

    • Content Type: application/json

{
&amp;amp;quot;Id&amp;amp;quot;:&amp;amp;quot;86ec9889-f148-4eba-9fc2-044b7accea39&amp;amp;quot;,
&amp;amp;quot;MSISDN&amp;amp;quot;:&amp;amp;quot;MSISDN&amp;amp;quot;,
&amp;amp;quot;BusinessShortCode&amp;amp;quot;:&amp;amp;quot;BusinessShortCode&amp;amp;quot;,
&amp;amp;quot;InvoiceNumber&amp;amp;quot;:&amp;amp;quot;InvoiceNumber&amp;amp;quot;,
&amp;amp;quot;TransID&amp;amp;quot;:&amp;amp;quot;TransID&amp;amp;quot;,
&amp;amp;quot;TransAmount&amp;amp;quot;:&amp;amp;quot;TransAmount&amp;amp;quot;,
&amp;amp;quot;ThirdPartyTransID&amp;amp;quot;:&amp;amp;quot;ThirdPartyTransID&amp;amp;quot;,
&amp;amp;quot;TransTime&amp;amp;quot;:&amp;amp;quot;TransTime&amp;amp;quot;,
&amp;amp;quot;BillRefNumber&amp;amp;quot;:&amp;amp;quot;BillRefNumber&amp;amp;quot;,
&amp;amp;quot;KYCInfoList&amp;amp;quot;:
[
{
&amp;amp;quot;KYCName&amp;amp;quot;:&amp;amp;quot;FirstName&amp;amp;quot;,
&amp;amp;quot;KYCValue&amp;amp;quot;:&amp;amp;quot;Foo&amp;amp;quot;
},
{
&amp;amp;quot;KYCName&amp;amp;quot;:&amp;amp;quot;MiddleName&amp;amp;quot;,
&amp;amp;quot;KYCValue&amp;amp;quot;:&amp;amp;quot;Doo&amp;amp;quot;
},
{
&amp;amp;quot;KYCName&amp;amp;quot;:&amp;amp;quot;LastName&amp;amp;quot;,
&amp;amp;quot;KYCValue&amp;amp;quot;:&amp;amp;quot;Bar&amp;amp;quot;
}
]
}

    • Content Type: application/xml,
  &amp;amp;lt;?xml version=&amp;amp;quot;1.0&amp;amp;quot; encoding=&amp;amp;quot;utf-8&amp;amp;quot; ?&amp;amp;gt;
                                &amp;amp;lt;instantpaymentnotification xmlns:xsi=&amp;amp;quot;http://www.w3.org/2001/XMLSchema-instance&amp;amp;quot; xmlns:xsd=&amp;amp;quot;http://www.w3.org/2001/XMLSchema&amp;amp;quot; id=&amp;amp;quot;C287557F-0A1D-C74F-8CE2-08D2E4F25CAC&amp;amp;quot;&amp;amp;gt;
                                    &amp;amp;lt;msisdn&amp;amp;gt;254700000000&amp;amp;lt;/msisdn&amp;amp;gt;
                                    &amp;amp;lt;businessshortcode&amp;amp;gt;217879&amp;amp;lt;/businessshortcode&amp;amp;gt;
                                    &amp;amp;lt;invoicenumber&amp;amp;gt;&amp;amp;lt;/invoicenumber&amp;amp;gt;
                                    &amp;amp;lt;transid&amp;amp;gt;JKH878879r7889734R9&amp;amp;lt;/transid&amp;amp;gt;
                                    &amp;amp;lt;transamount&amp;amp;gt;50.00&amp;amp;lt;/transamount&amp;amp;gt;
                                    &amp;amp;lt;thirdpartytransid&amp;amp;gt;&amp;amp;lt;/thirdpartytransid&amp;amp;gt;
                                    &amp;amp;lt;transtime&amp;amp;gt;20151106101346&amp;amp;lt;/transtime&amp;amp;gt;
                                    &amp;amp;lt;billrefnumber&amp;amp;gt;07000000&amp;amp;lt;/billrefnumber&amp;amp;gt;
                                    &amp;amp;lt;kycinfolist&amp;amp;gt;
                                        &amp;amp;lt;kycinfo&amp;amp;gt;
                                            &amp;amp;lt;kycname&amp;amp;gt;[Personal Details][First Name]&amp;amp;lt;/kycname&amp;amp;gt;
                                            &amp;amp;lt;kycvalue&amp;amp;gt;FirsName&amp;amp;lt;/kycvalue&amp;amp;gt;
                                        &amp;amp;lt;/kycinfo&amp;amp;gt;
                                        &amp;amp;lt;kycinfo&amp;amp;gt;
                                            &amp;amp;lt;kycname&amp;amp;gt;[Personal Details][Middle Name]&amp;amp;lt;/kycname&amp;amp;gt;
                                            &amp;amp;lt;kycvalue&amp;amp;gt;MiddleName&amp;amp;lt;/kycvalue&amp;amp;gt;
                                        &amp;amp;lt;/kycinfo&amp;amp;gt;
                                        &amp;amp;lt;kycinfo&amp;amp;gt;
                                            &amp;amp;lt;kycname&amp;amp;gt;[Personal Details][Last Name]&amp;amp;lt;/kycname&amp;amp;gt;
                                            &amp;amp;lt;kycvalue&amp;amp;gt;LastName&amp;amp;lt;/kycvalue&amp;amp;gt;
                                        &amp;amp;lt;/kycinfo&amp;amp;gt;
                                    &amp;amp;lt;/kycinfolist&amp;amp;gt;
                                &amp;amp;lt;/instantpaymentnotification&amp;amp;gt;

Validating C2B Transaction

Note:

  • The third party must validate the authenticity of C2B transaction. This can be done by calling API GET method and passing the ID parameter passed in the IPN message.

If the transaction is valid, the API will respond with HTTP code 200 otherwise HTTP code 403.

Below is an example of the GET request, authorization header must be included. /api/eft/8e33f7d8-ddf4-ca7f-c5c4-08d2e679d9v9

Response is as below:-

{
“Type”: 4,
“TypeDesc”: “Consumer to Business”,
“CompanyId”: “00000000-0000-0000-0000-000000000000”,
“CompanyDesc”: Company Description,
“Remarks”: “?”,
“IsDelivered”: false,
“OrderLines”: null
}

WeChat

Notes

  • RESTful web service
  • HTTP Basic Authentication over SSL
  • Test bed URL: http://52.20.176.4:8090/api/eft
  • This documentation is intended for programmers who are familiar with REST and JSON.

Overview

After a full integration, you will be able to make transfers to mobile money accounts, transfers to bank accounts in Kenya and to paybill and lipa na M-pesa tills. You will also be able to receive Instant Payment Notifications (IPN) whenever your configured paybill numbers/Lipa na M-pesa tills receive a payment in real-time.

Authentication

The client’s public IP address or API account must be whitelisted before access is granted. Logon credentials will also be provided together with the access grant. We shall provide the following test bed information prior to implementation:

  • CompanyID
  • Username
  • Password

Requests must be made using authenticated HTTP POST requests to certain URLs on the website.

Site URIs:

The authentication is HTTP basic auth using the username and password assigned. See https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side

Data Definition

    • Type Enumeration
Value Description
0 Transfer to a bank Account
1 Transfer to a mobile wallet
2 Business to Business e.g. Paybill, Lipa na M-pesa
    • Primary Account Number Enumeration
Value Description
Mobile Phone Number e.g. 254700000000 When type enumeration above is 1
Bank Account Number When type enumeration above is 0
Bill number (e.g. KPLC bill number – 888888, etc.) When type enumeration above is 2

Error Codes

Error Code Error Description
Error 401 Invalid Username and/or Password
Error 403 Missing Mandatory field(s)
Error 404 Invalid URL
Error 412 Wrong Company ID or Duplicate SystemTraceAuditNumber detected
Error 500 Invalid Bank branch code
Error 400 Query transaction with an Id that doesn’t exist
Error 429 Too many requests

Result Codes

Result Code Description
Code 0 Pending
Code 1 Queued
Code 2 Submit Acknowledged (M-Pesa acknowledges receipt)
Code 3 Completed
Code 4 Cached (at M-Pesa)
Code 5 Failed
Code 6 Submitted (to M-Pesa)
Code 7 Rejected

API Methods

Request

API Description
GET api/Request No documentation available.
GET api/Request/{id} No documentation available.
POST api/Request No documentation available.
GET api/Request?id={id} No documentation available.

Checkout

API Description
POST api/Checkout No documentation available.
PUT api/Checkout/{id} No documentation available.
DELETE api/Checkout/{id} No documentation available.
PUT api/Checkout?id={id} No documentation available.
DELETE api/Checkout?id={id} No documentation available.

WeChatCallback

API Description
GET api/WeChatCallback No documentation available.
GET api/WeChatCallback/{id} No documentation available.
POST api/WeChatCallback No documentation available.
GET api/WeChatCallback?id={id} No documentation available.

WeChat

API Description
GET api/WeChat No documentation available.
GET api/WeChat/{id} No documentation available.
POST api/WeChat No documentation available.
PUT api/WeChat/{id} No documentation available.
DELETE api/WeChat/{id} No documentation available.
GET api/WeChat?id={id} No documentation available.
PUT api/WeChat?id={id} No documentation available.
DELETE api/WeChat?id={id} No documentation available.

EFT

API Description
GET api/EFT No documentation available.
GET api/EFT/{id} No documentation available.
GET api/EFT?stan={stan} No documentation available.
POST api/EFT No documentation available.
DELETE api/EFT/{id} No documentation available.
GET api/EFT?id={id} No documentation available.
GET api/EFT/{stan} No documentation available.
DELETE api/EFT?id={id} No documentation available.

BalanceEnquiry

API Description
GET api/BalanceEnquiry/{id} No documentation available.
GET api/BalanceEnquiry?id={id} No documentation available.

Payment Notifications

Overview

This is intended for Third Party Developers who want to receive IPN (Instant Payment Notification) for M-pesa C2B (Customer to Business) transactions.

Receiving a C2B Notification

Note:

  • The end point URL will be provided by the intended user of this documentation.
  • The end point URL MUST be https.
  • The intended user will specify notification content type i.e application/xml or application/json

The following are the fields passed in the IPN message:

Field Data Type Description Format
MSISDN String Customer Mobile Number 254700000000
BusinessShortCode Integer Business short code provide by Safaricom 12345678
InvoiceNumber Varchar Invoice number ABC123
TransID Integer Unique Transaction Identifier hjfgerew
TransAmount Decimal Transaction Amount 1000.0
ThirdPartyTransID String Third Party Transaction ID TX1001
TransTime DateTime Transaction Date time 20140227082020
KYCInfo String Customer’s First, Second and last name XML

Note: If the above POST is successful, the third party should respond with HTTP code 200 and any other meta data they wish to respond with. Sample IPN Messages

    • Content Type: application/json

{
&amp;amp;quot;Id&amp;amp;quot;:&amp;amp;quot;86ec9889-f148-4eba-9fc2-044b7accea39&amp;amp;quot;,
&amp;amp;quot;MSISDN&amp;amp;quot;:&amp;amp;quot;MSISDN&amp;amp;quot;,
&amp;amp;quot;BusinessShortCode&amp;amp;quot;:&amp;amp;quot;BusinessShortCode&amp;amp;quot;,
&amp;amp;quot;InvoiceNumber&amp;amp;quot;:&amp;amp;quot;InvoiceNumber&amp;amp;quot;,
&amp;amp;quot;TransID&amp;amp;quot;:&amp;amp;quot;TransID&amp;amp;quot;,
&amp;amp;quot;TransAmount&amp;amp;quot;:&amp;amp;quot;TransAmount&amp;amp;quot;,
&amp;amp;quot;ThirdPartyTransID&amp;amp;quot;:&amp;amp;quot;ThirdPartyTransID&amp;amp;quot;,
&amp;amp;quot;TransTime&amp;amp;quot;:&amp;amp;quot;TransTime&amp;amp;quot;,
&amp;amp;quot;BillRefNumber&amp;amp;quot;:&amp;amp;quot;BillRefNumber&amp;amp;quot;,
&amp;amp;quot;KYCInfoList&amp;amp;quot;:
[
{
&amp;amp;quot;KYCName&amp;amp;quot;:&amp;amp;quot;FirstName&amp;amp;quot;,
&amp;amp;quot;KYCValue&amp;amp;quot;:&amp;amp;quot;Foo&amp;amp;quot;
},
{
&amp;amp;quot;KYCName&amp;amp;quot;:&amp;amp;quot;MiddleName&amp;amp;quot;,
&amp;amp;quot;KYCValue&amp;amp;quot;:&amp;amp;quot;Doo&amp;amp;quot;
},
{
&amp;amp;quot;KYCName&amp;amp;quot;:&amp;amp;quot;LastName&amp;amp;quot;,
&amp;amp;quot;KYCValue&amp;amp;quot;:&amp;amp;quot;Bar&amp;amp;quot;
}
]
}

    • Content Type: application/xml,
  &amp;amp;lt;?xml version=&amp;amp;quot;1.0&amp;amp;quot; encoding=&amp;amp;quot;utf-8&amp;amp;quot; ?&amp;amp;gt;
                                &amp;amp;lt;instantpaymentnotification xmlns:xsi=&amp;amp;quot;http://www.w3.org/2001/XMLSchema-instance&amp;amp;quot; xmlns:xsd=&amp;amp;quot;http://www.w3.org/2001/XMLSchema&amp;amp;quot; id=&amp;amp;quot;C287557F-0A1D-C74F-8CE2-08D2E4F25CAC&amp;amp;quot;&amp;amp;gt;
                                    &amp;amp;lt;msisdn&amp;amp;gt;254700000000&amp;amp;lt;/msisdn&amp;amp;gt;
                                    &amp;amp;lt;businessshortcode&amp;amp;gt;217879&amp;amp;lt;/businessshortcode&amp;amp;gt;
                                    &amp;amp;lt;invoicenumber&amp;amp;gt;&amp;amp;lt;/invoicenumber&amp;amp;gt;
                                    &amp;amp;lt;transid&amp;amp;gt;JKH878879r7889734R9&amp;amp;lt;/transid&amp;amp;gt;
                                    &amp;amp;lt;transamount&amp;amp;gt;50.00&amp;amp;lt;/transamount&amp;amp;gt;
                                    &amp;amp;lt;thirdpartytransid&amp;amp;gt;&amp;amp;lt;/thirdpartytransid&amp;amp;gt;
                                    &amp;amp;lt;transtime&amp;amp;gt;20151106101346&amp;amp;lt;/transtime&amp;amp;gt;
                                    &amp;amp;lt;billrefnumber&amp;amp;gt;07000000&amp;amp;lt;/billrefnumber&amp;amp;gt;
                                    &amp;amp;lt;kycinfolist&amp;amp;gt;
                                        &amp;amp;lt;kycinfo&amp;amp;gt;
                                            &amp;amp;lt;kycname&amp;amp;gt;[Personal Details][First Name]&amp;amp;lt;/kycname&amp;amp;gt;
                                            &amp;amp;lt;kycvalue&amp;amp;gt;FirsName&amp;amp;lt;/kycvalue&amp;amp;gt;
                                        &amp;amp;lt;/kycinfo&amp;amp;gt;
                                        &amp;amp;lt;kycinfo&amp;amp;gt;
                                            &amp;amp;lt;kycname&amp;amp;gt;[Personal Details][Middle Name]&amp;amp;lt;/kycname&amp;amp;gt;
                                            &amp;amp;lt;kycvalue&amp;amp;gt;MiddleName&amp;amp;lt;/kycvalue&amp;amp;gt;
                                        &amp;amp;lt;/kycinfo&amp;amp;gt;
                                        &amp;amp;lt;kycinfo&amp;amp;gt;
                                            &amp;amp;lt;kycname&amp;amp;gt;[Personal Details][Last Name]&amp;amp;lt;/kycname&amp;amp;gt;
                                            &amp;amp;lt;kycvalue&amp;amp;gt;LastName&amp;amp;lt;/kycvalue&amp;amp;gt;
                                        &amp;amp;lt;/kycinfo&amp;amp;gt;
                                    &amp;amp;lt;/kycinfolist&amp;amp;gt;
                                &amp;amp;lt;/instantpaymentnotification&amp;amp;gt;

Validating C2B Transaction

Note:

  • The third party must validate the authenticity of C2B transaction. This can be done by calling API GET method and passing the ID parameter passed in the IPN message.

If the transaction is valid, the API will respond with HTTP code 200 otherwise HTTP code 403.

Below is an example of the GET request, authorization header must be included. /api/eft/8e33f7d8-ddf4-ca7f-c5c4-08d2e679d9v9

Response is as below:-

{
“Type”: 4,
“TypeDesc”: “Consumer to Business”,
“CompanyId”: “00000000-0000-0000-0000-000000000000”,
“CompanyDesc”: Company Description,
“Remarks”: “?”,
“IsDelivered”: false,
“OrderLines”: null
}

C#


C# (pronounced “C sharp”) is a programming language that is designed for building a variety of applications that run on the .NET Framework. C# is simple, powerful, type-safe, and object-oriented. The many innovations in C# enable rapid application development while retaining the expressiveness and elegance of C-style languages.


Java


Java is a programming language and computing platform first released by Sun Microsystems in 1995. There are lots of applications and websites that will not work unless you have Java installed, and more are created every day. Java is fast, secure, and reliable. From laptops to datacenters, game consoles to scientific supercomputers, cell phones to the Internet, Java is everywhere!


PHP


PHP is an HTML-embedded scripting language. Much of its syntax is borrowed from C, Java and Perl with a couple of unique PHP-specific features thrown in. The goal of the language is to allow web developers to write dynamically generated pages quickly. PHP stands for PHP: Hypertext Preprocessor. This confuses many people because the first word of the acronym is the acronym. This type of acronym is called a recursive acronym.


What is PFS?

PFS stands for Pi Financial Suite and it’s a payments processing engine.

Who can use PFS?

Any individual or company that constantly processes payments to mobile money and/or bank accounts in Kenya.

How can I use PFS?

To transfer funds to bank accounts and mobile money accounts in Kenya

Do you support all mobile money providers in Kenya?

Currently we only support transfers to M-pesa but other partners are coming soon.

Can I send money to a bank account in Kenya?

Yes to a majority of the bank accounts in Kenya. Credits are real-time

Can I send money to other countries using PFS?

Currently no but we are in talks with partners in Uganda, Tanzania and Rwanda to terminate transactions for us.

What are the charges?

We charge a friendly transactional fee. Get in touch with us for a quote: sales[at]pycs.co.ke

When are the charges due?

The charge is applied for every successful transfer.

How do I reset my password?

Reset your password here

How can I initiate a funds transfer?

Using a maker-checker process, one can upload instructions through our web portal.

Do you have an API?

Yes

If yes, what kind of an API is it?

It’s a restful API

Do you have any documentation for the API?

Yes, see it here

How can I delete my account?

Send us an email to support[at]pycs.co.ke and we’ll delete the account for you.

How do I create an account?

Register here

What is a B2C account?

A business to consumer account is an account owned by a business and used to send funds to its customers/partners/employees.

What is a Paybill account?

This is an account used by a business to receive funds from its customers.

What is a Lipa na M-pesa Account?

This is an M-pesa business account used by businesses to receive funds from consumers

What happens to my money if my account is inactive?

Your money remains available for transacting or withdrawal.

Do I have to open a business account with Safaricom?

Yes. We can use your existing account if you already have one.

Can you help me open an account with Safaricom?

We can advise on the requirements and fast-track the account creation process

How do I top up my account?

Once your B2C account is created, the M-pesa team will guide on this process/p>

How will I know if my transactions have been processed?

The system sends email alerts for all processed transactions showing the status of the transaction. You can also check the status of the transaction from the portal.

My transfers are pending what do I do?

Contact us on support[at]pycs.co.ke

Send us an email on support[at]pycs.co.ke or Skype us on pycs.support

Development.Integrations.Payments
Internships | Privacy Policy
Copyright © 2017 Pi Consulting Services Limited.