B2B

 

Developer Guide


This guide specifies real time B2B web service aspects of the interfaces which include:

  • Message Flow Description
  • Data Type Definition
  • Web Service Interface Definition
  • Transaction Types Description
  • WSDL
  • Examples

 

API Framework Overview


This document details the interface specification for a real time M-Pesa transaction API delivered within the MPesa Core API Framework. The Core API defines an abstract model for API requests which includes 4 distinct parties to API operations, as well as a generic set of API operation parameters.

Initiators are the organization or entity requesting that an API operation or transaction is performed.

Caller is the actual piece of software which communicates with the MPesa Core API web service.

Primary Party is (typically) the debit party within an existing MPesa financial transaction.

Receiver Party is correspondingly the credit party in an MPesa financial transaction

 

Message Flow Description


B2C high-level transaction flow diagram

B2B high-level transaction flow diagram

 

Data Type Definition


IdentityType enumeration

Enumeration Description
1000 Customer
2000 SPOperator
3000 OrganizationOperator
5000 Organization
6000 Till
8000 SP

 

IdentifierType enumeration

Enumeration Description
1 MSISDN
2 TillNumber
3 SPShortCode
4 OrganizationShortCode
5 IdentityID
6 O2CLink
9 SPOperatorCode
10 POSNumber
11 OrganizationOperatorUserName
12 OrganizationOperatorCode
13 VoucherCode

 

ParameterType structure

Element name Element type Optional Description
Key xsd:string No It indicates a parameter name.
Value xsd:string No It indicates a parameter value.

 

Parameters structure

Element name Element type Optional Description
Parameter ParameterType[1..unbounded] No It is used to carry specific parameters for specific transaction or business operation.

 

ReferenceData structure

Element name Element type Optional Description
ReferenceItem ParameterType[1..unbounded] No It is used carry some reference data that MM need not analyze but need to record it into transaction log..

 

Transaction structure

Element name Element type Optional Description
CommandID xsd:string No The unique identifier of transaction/business operation. Max length is 64.eg
·         BusinessBuyGoods
·         BusinessPayBill
·         DisburseFundsToBusiness
·         BusinessToBusinessTransfer
·         BusinessTransferFromMMFToUtility
·         BusinessTransferFromUtilityToMMF
·         MerchantToMerchantTransfer
·         MerchantTransferFromMerchantToWorking
·         MerchantTransferFromWorkingToMerchant
·         OrgBankAccountWithdrawal
·         OrgRevenueSettlement
·         MerchantServicesMMFAccountTransfer
·         AgencyFloatAdvance
LanguageCode xsd:string Yes It indicates language. It’s reserved.
OriginatorConversationID xsd:string No The unique identifier of the request message generated by third party. It is used to identify a request between the third party and MM. Max length is 128.
Field must start with the Organisation short and name of organisation. Eg.
232323_KCBOrg_XXXXXX
XXXXX must be unique for every transaction.
ConversationID xsd:string Yes The unique identifier generated by MM for a previous request message. It is used to support communication multi-times between the third party and MM for one operation/transaction.
Remark xsd:string Yes The remark information about this operation. Max length is 255
Parameters Parameters Yes It is used to carry specific parameters for specific transaction or business operation.
If the element EncryptedParameters presents, this parameter should not present.
ReferenceData ReferenceData Yes It is used carry some reference data that MM need not analyze but need to record it into transaction log.
Timestamp xsd:string No The timestamp generated by the third party.

 

Caller structure

Element name Element type Optional Description
CallerType xsd:integer No Indicates the type of the caller:
2-APICaller
3-Other(Reserved)
ThirdPartyID xsd:string No The unique identifier of a third party system defined in MM. It indicates the third party which initiates the request. Max length is 20
Password xsd:string Yes This security credential of the ThirdPartyID defined in MM. If the password feature for third party is used in MM, then this parameter must be presented in the request message.
CheckSum xsd:string Yes Currently it is unused. It is reserved for API security.
ResultURL xsd:string Yes It indicates the destination URL where Broker should send the result message to.

 

Initiator structure

Element name Element type Optional Description
IdentifierType IdentifierType No It indicates the identifier type of the initiator. The value of this parameter must be a valid identifier type supported by MM.
Identifier xsd:string No It indicates the identifier of the initiator. Its value must match the inputted value of the parameter IdentifierType.
SecurityCredential xsd:string No It indicates the security credential of the initiator. Its value must match the inputted value of the parameter IdentifierType.
ShortCode xsd:string Yes When the initiator is an organization operator, this parameter must be present in the request to indicate which organization the operator belongs to.
If the initiator is not an organization operator, this parameter should not be present.

 

N/B: Password Encryption

The Caller will be required to confirm its authority to act on behalf of the Initiator (i.e. a specific M-PESA organisation) by presenting the user name and password for the Initiator, the latter encrypted with the public key from an X509 certificate issued to the Initiator specifically for this purpose. The following algorithm must be followed by the Initiator to encrypt passwords:

  • Write the unencrypted password value
  • Then, encrypt the value with the public portion of the password key certificate.  Use the RSA algorithm, and use PKCS #1.5 padding (not OAEP), and add the result to the encrypted stream.
  • Convert the resulting encrypted byte array into a string using base64 encoding.  Present this base64 encoded string in the API request as the initiator SecurityCredential value

 

PrimaryParty structure

Element name Element type Optional Description
IdentifierType IdentifierType No It indicates the identifier type of the primary party. The value of this parameter must be a valid identifier type supported by MM and must match the inputted value of the parameter IdentityType.
Identifier xsd:string No It indicates a parameter value.
ShortCode xsd:string Yes It is reserved

 

ReceiverParty structure

Element name Element type Optional Description
IdentifierType IdentifierType No It indicates the identifier type of the recipient party. The value of this parameter must be a valid identifier type supported by MM.
Identifier xsd:string No It indicates the identifier of the recipient party. Its value must match the inputted value of the parameter IdentifierType.
ShortCode xsd:string Yes When the receiver party is an organization operator or a Till, this parameter must be present in the request to indicate which organization the receiver party belongs to.
If the receiver party is not an organization operator or a Till, this parameter should not be present.

 

AccessDevice structure

Element name Element type Optional Description
IdentifierType IdentifierType No It indicates the identifier type of the access device.
Identifier xsd:string No It indicates the identifier of the access device. Its value must match the inputted value of parameter IdentifierType

 

Identity structure

Element name Element type Optional Description
Caller Caller No It indicates the third party which initiates the request
Initiator Initiator No It indicates the identity who makes the request. An initiator must be one of the following identity types:
l  SP operator
l  Organization operator(11)
NOTE
The value “11”(Organization Operator)or ‘14’(SP Operator) will be used for all the services in this document.
PrimartyParty PrimartyParty Yes If business operation/action, this element is not present; if transaction, this can be either the debit party or the credit party according to the transaction type.
ReceiverParty ReceiverParty Yes If business operation/action, this is the affected party; if transaction, it is the opposite party to the PrimaryParty
AccessDevice AccessDevice Yes It indicates the access device which the initiator uses to initiate the request.

 

Request structure

Element name Element type Optional Description
Transaction Transaction No It indicates a transaction.
Identity Identity No This section is used to specify all identities involved in the request
KeyOwner xsd:integer No It indicates which Key is used to encrypt the elements Initator.SecurityCredential and the EncryptedParameters.
Its value are enumerated as follows:
1:the API Caller’s Key
2:the Initiator’s Key

 

Response structure

Element name Element type Optional Description
ResponseCode xsd:string No It indicates whether MM accepts the request or not.
ResponseDesc xsd:string Yes Its value is a description for the parameter ResultCode.
ConversationID xsd:string Yes The unique identifier generated by M-Pesa for the request message.
OriginatorConversationID xsd:string Yes The unique identifier generated by the third party for the request message.
ServiceStatus xsd: integer Yes It indicates the MM service status.

 

ResultParameters structure

Element name Element type Optional Description
ResultParameter ParameterType[0…unbounded] Yes It is used to carry specific parameters for specific transaction or business operation.

 

Result structure

Element name Element type Optional Description
ResultType xsd:integer Yes 0: completed 1: waiting for further messages
ResultCode xsd:string No It indicates whether MM processes the request successfully or not. Max length is 10
ResultDesc xsd:string Yes Its value is a description for the parameter ResultCode.Max length is 1024
OriginatorConversationID xsd:string Yes The unique identifier of the request message generated by third party. Its value comes from the request message.
ConversationID xsd:string Yes The unique identifier generated by MM for a request
TransactionID xsd:string Yes It’s only for transaction. When the request is a transaction request, MM will generate a unique identifier for the transaction.
ResultParameters ResultParameters Yes It is used to carry specific parameters for specific transaction or business operation.
ReferenceData ReferenceData Yes It comes from the request message

 

Result code

Error code Error Description
0 Success ApiResult
1 Insufficient Funds ApiResult
2 Less Than Minimum Transaction Value ApiResult
3 More Than Maximum Transaction Value ApiResult
4 Would Exceed Daily Transfer Limit ApiResult
5 Would Exceed Minimum Balance ApiResult
6 Unresolved Primary Party ApiResult
7 Unresolved Receiver Party ApiResult
8 Would Exceed Maxiumum Balance ApiResult
11 Debit Account Invalid ApiResult
12 Credit Account Invaliud ApiResult
13 Unresolved Debit Account ApiResult
14 Unresolved Credit Account ApiResult
15 Duplicate Detected ApiResult
17 Internal Failure ApiResult
18 Initiator Credential Check Failure ApiResult
19 Message Sequencing Failure ApiResult
20 Unresolved Initiator ApiResult
21 Initiator to Primary Party Permission Failure ApiResult
22 Initiator to Receiver Party Permission Failure ApiResult
23 Request schema validation error ApiResponse
24 Missing mandatory fields ApiResponse
25 Cannot communicate with Caller ApiResponse
26 Traffic blocking condition in place ApiResponse
0 Success ApiResponse
100000000 Request was cached, waiting for resending ApiResponse
100000001 The system is overload ApiResponse
100000002 Throttling error ApiResponse
100000003 Exceed the limitation of the LICENSE ApiResponse
100000004 Internal Server Error ApiResponse
100000005 Invalid input value:%1 ApiResponse
%1 indicates the parameter’s name.
100000006 SP’s status is abnormal ApiResponse
100000007 Authentication failed ApiResponse
100000008 Service’s status is abnormal ApiResponse
100000009 API’s status is abnormal ApiResponse
100000010 Insufficient permissions ApiResponse
100000011 Exceed the limitation of request rate ApiResponse
100000012 Insufficient balance ApiResponse
100000013 No route ApiResponse
100000014 Missing mandatory parameter:%1 ApiResponse
%1 indicates the parameter’s name.

 

 

Web Service Interface Definition


Interface: RequestMgrPortType

Operation: GenericAPIRequest

The 3rd party invokes this operation to send a B2B request

Message Header: RequestSOAPHeader
Element name Element type Optional Description
SpId xsd: string No SP ID.
This is the Service Provider Identifier that is allocated by the Broker to the 3rd party.
[Example] : 888777
SpPassword xsd: string Yes This is an encrypted form of the SP password issued to an SP when an account is created on the Broker.
The encrypted password is a Base64 encoded string of the SHA-256 hash of the concatenation of the spId, password and the timeStamp as illustrated below:
Given the following parameters
spId: 888777
password: spPassword
timestamp: 20130702212854
spPassword = BASE64(SHA-256(spId + Password + timeStamp)) e.g.
spPassword = BASE64(SHA-256(888777spPassword20130702212854)
[Example] : e6434ef249df55c7a21a0b45758a39bb
ServiceId xsd: string Yes Service ID.
This is the Service Identifier that is allocated by the Broker for every service created.
[Example] : 888777000
Timestamp xsd: string Yes Time stamp (UTC time).
The value is required during SHA-256 encryption for spPassword.
NOTE
If the spPassword parameter must be set, this parameter is mandatory.
[Format]
yyyyMMddHHmmss
[Example] : 20161127093550
Input Message: RequestMsg
Element name Element type Optional Description
RequestMsg xsd: string No Request Message from 3rd party. Its value should be an instance of Request Type and a CDATA

N/B:

If there is no configuration for notification URL on Broker side, which indicates the callback url for accepting notification of GenericAPIResult or/and notification of cached requests expired, the ResultURL parameter inside Identity tag and a QueueTimeoutURL parameter in ReferenceData tag must be present respectively.

Output Message: ResponseMsg
Element name Element type Optional Description
ResponseMsg xsd: string No Response return to 3rd party. Its value should be an instance of Response Type and a CDATA.

 

Interface: ResultMgrPortType

Operation: GenericAPIResult

This operation must be implemented by a Web Service at the 3rd party side if it requires notification of the final result for B2B request. It will be invoked by Broker to notify the 3rd party once Broker received the notification from Core API.

Input Message: ResultMsg
Element name Element type Optional Description
ResultMsg xsd: string No Request Message from Broker. Its value should be a instance of Result Type and a CDATA.
Output Message: ResponseMsg
Element name Element type Optional Description
ResponseMsg xsd: string No Response return to Broker. Its value should be a instance of Response Type and a CDATA.

 

Interface: QueueTimeoutNotificationPort

Operation: notifyQueueTimeout

This operation must be implemented by a Web Service at the 3rd party side if it requires notification of expired cached requests. It will be invoked by Broker to notify the 3rd party once cached requests are expired

Input Message: notifyQueueTimeout
Element name Element type Optional Description
OriginatorConversationID xsd:string originatorConversationID from the request sent by the 3rd party
originRequest xsd:string No Original request without SOAP Header sent by 3rd party. Its value is encoded with base64, when the 3rd party receive the request, it should decode it.
ExtensionInfo Parameters Yes Extended parameters.
Output Message: notifyQueueTimeoutResponse
Element name Element type Optional Description
Result Result No
ExtensionInfo Parameters Yes Extended parameters.
Response Codes
ResponseCode ResponseDesc
0 Success
1 Failed

 

Interface: QueryTransactionPort

Operation: queryTransaction

The 3rd party invokes this operation to query transaction information.

Message Header: RequestSOAPHeader
Element name Element type Optional Description
SpId xsd: string No SP ID.
It’s allocated by the Broker to the 3rd party.
 [Example] : 888777
spPassword xsd: string Yes This is an encrypted form of the SP password issued to an SP when an account is created on the Broker.
The encrypted password is a Base64 encoded string of the SHA-256 hash of the concatenation of the spId, password and the timeStamp as illustrated below:
Given the following parameters
spId: 888777
password: spPassword
timestamp: 20130702212854
spPassword = BASE64(SHA-256(spId + Password + timeStamp)) e.g.
spPassword = BASE64(SHA-256(888777spPassword20130702212854)
[Example] : e6434ef249df55c7a21a0b45758a39bb
ServiceID xsd: string Yes The value is allocated by the Broker to the 3rd party.
 [Example] : 888777000
timeStamp xsd: string Yes Time stamp (UTC time).
The value is required during SHA-256 encryption for spPassword.
NOTE
If the spPassword parameter must be set, this parameter is mandatory.
[Format] : yyyyMMddHHmmss
[Example] : 20161127093550
Input Message: queryTransaction
Element name Element type Optional Description
originatorConversationID xsd:string The unique identifier of the request message generated by third party. It is used to identify a request between the third party and MM. Max length is 128
extensionInfo Parameters Yes Extended parameters.
ExtensionInfo Description
Parameter Optional Type Description
queryDate Yes String(20) The date of the original conversation. Format is yyyyMMddHHmmss, for example: 20131230134412
If this parameter does not present, it will cost more time to get the result.
Output Message: queryTransactionResponse
Element name Element type Optional Description
Result Response No
submitApiRequestList xsd:string[0-unbounded] Y Requests sent by the 3rd party. Its value is the requests sent by the 3rd party with base64 encoded.
submitApiResponseList xsd:string[0-unbounded] Y Responses returned from the Broker. Its value is the responses returned from the Broker with base64 encoded.
submitApiResultList xsd:string[0-unbounded] Y Results sent to the 3rd party. Its value is the requests sent by the Broker with base64 encoded.
queueTimeOutList xsd:string[0-unbounded] Y QueueTimeout requests sent to the 3rd party. Its value is the requests sent by the Broker with base64 encoded.
extensionInfo Parameters Yes Extended parameters.
Response Codes
ResponseCode ResponseDesc
0 Success
100000001 The system is overload
100000002 Throttling error
100000003 Exceed the limitation of the LICENSE
100000004 Internal Server Error
100000005 Invalid input value:%1
%1 indicates the parameter’s name.
100000006 SP’s status is abnormal
100000007 Authentication failed
100000008 Service’s status is abnormal
100000010 Insufficient permissions
100000014 Missing mandatory parameter:%1
%1 indicates the parameter’s name.

 

Interface: Management

Operation: changePassword

The 3rd party invokes this operation to change their password.

Input Message: changePassword
Element name Element type Optional Description
SpId xsd: string No SP ID.
This is the Service Provider Identifier that is allocated by the Broker to the 3rd party.
[Example] : 888777
SpPassword xsd: string Yes This is an encrypted form of the SP password issued to an SP when an account is created on the Broker.
The encrypted password is a Base64 encoded string of the SHA-256 hash of the concatenation of the spId, password and the timeStamp as illustrated below:
Given the following parameters
spId: 888777
password: spPassword
timestamp: 20130702212854
spPassword = BASE64(SHA-256(spId + Password + timeStamp)) e.g.
spPassword = BASE64(SHA-256(888777spPassword20130702212854)
[Example] : e6434ef249df55c7a21a0b45758a39bb
Timestamp xsd: string Yes Time stamp (UTC time).
The value is required during SHA-256 encryption for spPassword.
NOTE
If the spPassword parameter must be set, this parameter is mandatory.
[Format]
yyyyMMddHHmmss
[Example] : 20161127093550
newPassword xsd:string No New authentication password for 3rd parties to access the SAG. It should be encrypted by AES-256 and encoded with base64. Shared key and will be allocated by the SAG.
For example:
New password is !QAZ2wsx,
Security key is AAAabcdefghijklm,
Vector is abcdefghijklmnop
AES(!QAZ2wsx, AAAabcdefghijklm, abcdefghijklmnop) is wi2a7BAH0QPd2LRdmcgC9w==
SP should fill wi2a7BAH0QPd2LRdmcgC9w== as newPassword
extensionInfo Parameters Yes Extended parameters.
Output Message: changePasswordResponse
Element name Element type Optional Description
result Result No Result.
extensionInfo Parameters Yes Extended parameters.
Response Codes
ResponseCode ResponseDesc
0 Success
100000001 The system is overload
100000002 Throttling error
100000003 Exceed the limitation of the LICENSE
100000004 Internal Server Error
100000005 Invalid input value:%1
%1 indicates the parameter’s name.
100000006 SP’s status is abnormal
100000007 Authentication failed
100000014 Missing mandatory parameter:%1
%1 indicates the parameter’s name.

 

Transaction Types


Request Party Matrix

Command Types InitiatorLinkedTo Primary Party Receiver Party
BusinessBuyGoods C2B, B2C,  Merchant HO and Store Identity – C2B, B2C,  Merchant HO and Store Identity – Merchant HO and Store
IdentifierType – 4 IdentifierType – 4
Identifier – ShortCode Identifier – ShortCode
BusinessPayBill C2B, B2C,  Merchant HO and Store Identity – C2B, B2C,  Merchant HO and Store Identity – C2B Business
IdentifierType – 4 IdentifierType – 4
Identifier – ShortCode Identifier – ShortCode
DisburseFundsToBusiness B2C and C2B Business Identity –C2B and B2C Identity – C2B, B2C,  Merchant HO and Store
IdentifierType – 4 IdentifierType – 4
Identifier – ShortCode Identifier – ShortCode
BusinessToBusinessTransfer C2B, B2C,  Merchant HO and Store, Agency HO and store Identity – C2B, B2C,  Merchant HO and Store Identity – C2B, B2C,  Merchant HO and Store
IdentifierType – 4 IdentifierType – 4
Identifier – ShortCode Identifier – ShortCode
BusinessTransferFromMMFToUtility C2B, B2C Identity –C2B and B2C Same as Primary Party
IdentifierType – 4
Identifier – ShortCode
BusinessTransferFromUtilityToMMF C2B, B2C Identity –C2B and B2C Same as Primary Party
IdentifierType – 4
Identifier – ShortCode
MerchantTransferFromMerchantToWorking Merchant HO and Store Identity – Merchant HO and Store Same as Primary Party
IdentifierType – 4
Identifier – ShortCode
MerchantTransferFromWorkingToMerchant Merchant HO and Store Identity – Merchant HO and Store Same as Primary Party
IdentifierType – 4
Identifier – ShortCode
MerchantToMerchantTransfer Merchant HO and Store (Out of hierarchy). The short code must be the Store shortCode or HO shortcode Identity – Merchant HO and Store Identity – Merchant HO and Store
IdentifierType – 4 IdentifierType – 4
Identifier – ShortCode Identifier – ShortCode
MerchantServicesMMFAccountTransfer Merchant HO and Store (Within Hierachy). The short code must be the Store shortcode or HO shortcode Identity – Merchant HO and Store Identity – Merchant HO and Store
IdentifierType – 4 IdentifierType – 4
Identifier – ShortCode Identifier – ShortCode
AgencyFloatAdvance Agency HO and Store Identity – Agency HO and Store Identity – Agency HO and Store
IdentifierType – 4 IdentifierType – 4
Identifier – ShortCode Identifier – ShortCode
OrgBankAccountWithdrawal C2B, B2C,  Merchant HO and Store Identity – C2B, B2C,  Merchant HO and Store Same as Primary Party
IdentifierType – 4
Identifier – ShortCode
OrgRevenueSettlement C2B, B2C,  Merchant HO and Store Identity – C2B, B2C,  Merchant HO and Store Same as Primary Party
IdentifierType – 4
Identifier – ShortCode
AccountBalance B2C Business, NA (0) NA(0)
C2B Business,
Merchant HO,
MMF Organisation
TransactionStatusQuery B2C Business, NA (0) NA(0)
C2B Business,
Merchant HO,
MMF Organisation

 

Business Paybill
Description
This is a transaction type that moves money from Business customer (B2C, C2B, Merchant HO and Merchant Store organizations) to a C2B organization. The request moves money from the Primary Party’s MMF/WORKING account to the Receiver party’s Utility account. Primary party will be API Enabled Business Customer and receiver party will be C2B Business. The initiator would be linked to primary party
Input Parameters
Amount Decimal
AccountReference String The third party account reference. (Mandatory)
Output Parameters
ResultType ResultType It describes the state of the request, for single staged it would be only completed.
ResultCode String Result code
ResultDesc String Result description
ConversationId GUID M-Pesa conversation id
OriginatorConversationId String Third party conversation id
TransactionId String It takes the financial transaction unique receipt number.
ResultParameters
Amount Decimal The transactional Amount
Eg. <Key>Amount</Key><Value>7000.00</Value>
TransCompletedTime DateTime The date time when the transaction was completed.
Eg. <Key>TransCompletedTime</Key>
<Value>20150424170252</Value>
InitiatorAccountCurrentBalance Decimal Amount of money in the initiating organization.
Eg. <Key>InitiatorAccountCurrentBalance</Key>
<Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value>
DebitPartyCharges Decimal
DebitAccountCurrentBalance Decimal Amount of money in the initiating organization.
Eg. <Key> DebitAccountCurrentBalance </Key>
<Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value>
Currency String Currency used.
Eg. <Key>Currency</Key>
<Value>KES</Value>
DebitPartyPublicName String Public name of the Debit Party.
Format: <Short Code>-<Organization Name>
ReceiverPartyPublicName String Public name of the Credit Party.
Eg. <Key>ReceiverPartyPublicName</Key>
<Value>888888 – KPLC TEST</Value>.
DebitPartyAffectedAccountBalance String Indicates the account balance of all the affected accounts of debit party。
For each account, the fields are presented in the following order and separated by vertical bars (|):
amp; is used as the separator of different accounts.
Eg. <Key>DebitPartyAffectedAccountBalance</Key>
<Value>MMF Organization Account|KES|2714803.00|2714803.00|0.00|50000000.00</Value>

 

Disburse Funds to Business
Description
This is a transaction type that moves money from B2C and C2B organizations to a Business Customer (B2C, C2B, Merchant HO and Merchant Store organization). The request moves money from the Primary Party’s Utility account to the Receiver party’s MMF account. Primary party will be API Enabled Business Customer and receiver party will be a Business Customer. The initiator would be linked to primary party.
Input Parameters
Amount Decimal
AccountReference String The third party account reference. (optional)
Output Parameters
ResultType ResultType It describes the state of the request, for single staged it would be only completed.
ResultCode String Result code
ResultDesc String Result description
ConversationId GUID M-Pesa conversation id
OriginatorConversationId String Third party conversation id
TransactionId String It takes the financial transaction unique receipt number.
ResultParameters
Amount Decimal The transactional Amount
Eg. <Key>Amount</Key><Value>7000.00</Value>
TransCompletedTime DateTime The date time when the transaction was completed.
Eg. <Key>TransCompletedTime</Key>
<Value>20150424170252</Value>
InitiatorAccountCurrentBalance Decimal Amount of money in the initiating organization.
Eg. <Key>InitiatorAccountCurrentBalance</Key>
<Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value>
DebitPartyCharges Decimal
DebitAccountCurrentBalance Decimal Amount of money in the initiating organization.
Eg. <Key> DebitAccountCurrentBalance </Key>
<Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value>
Currency String Currency used.
Eg. <Key>Currency</Key>
<Value>KES</Value>
DebitPartyPublicName String Public name of the Debit Party.
Format: <Short Code>-<Organization Name>
ReceiverPartyPublicName String Public name of the Credit Party.
Eg. <Key>ReceiverPartyPublicName</Key>
<Value>888888 – KPLC TEST</Value>.
DebitPartyAffectedAccountBalance String Indicates the account balance of all the affected accounts of debit party。
For each account, the fields are presented in the following order and separated by vertical bars (|):
amp; is used as the separator of different accounts.
Eg. <Key>DebitPartyAffectedAccountBalance</Key>
<Value>MMF Organization Account|KES|2714803.00|2714803.00|0.00|50000000.00</Value>

 

Business Buy Goods
Description
This is a transaction type that moves money from Business customer (B2C, C2B, Merchant HO and Merchant Store organizations) to a Merchant HO or Store. The request moves money from the Primary Party’s MMF/WORKING account to the Receiver party’s Merchant account. Primary party will be API Enabled Business Customer and receiver party will be Merchant HO and Store Business. The initiator would be linked to primary party
Input Parameters
Amount Decimal
AccountReference String The third party account reference. (optional)
Output Parameters
ResultType ResultType It describes the state of the request, for single staged it would be only completed.
ResultCode String Result code
ResultDesc String Result description
ConversationId GUID M-Pesa conversation id
OriginatorConversationId String Third party conversation id
TransactionId String It takes the financial transaction unique receipt number.
ResultParameters
Amount Decimal The transactional Amount
Eg. <Key>Amount</Key><Value>7000.00</Value>
TransCompletedTime DateTime The date time when the transaction was completed.
Eg. <Key>TransCompletedTime</Key>
<Value>20150424170252</Value>
InitiatorAccountCurrentBalance Decimal Amount of money in the initiating organization.
Eg. <Key>InitiatorAccountCurrentBalance</Key>
<Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value>
DebitPartyCharges Decimal
DebitAccountCurrentBalance Decimal Amount of money in the initiating organization.
Eg. <Key> DebitAccountCurrentBalance </Key>
<Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value>
Currency String Currency used.
Eg. <Key>Currency</Key>
<Value>KES</Value>
DebitPartyPublicName String Public name of the Debit Party.
Format: <Short Code>-<Organization Name>
ReceiverPartyPublicName String Public name of the Credit Party.
Eg. <Key>ReceiverPartyPublicName</Key>
<Value>888888 – KPLC TEST</Value>.
DebitPartyAffectedAccountBalance String Indicates the account balance of all the affected accounts of debit party。
For each account, the fields are presented in the following order and separated by vertical bars (|):
amp; is used as the separator of different accounts.
Eg. <Key>DebitPartyAffectedAccountBalance</Key>
<Value>MMF Organization Account|KES|2714803.00|2714803.00|0.00|50000000.00</Value>

 

BusinessToBusinessTransfer
Description
This is a transaction type that moves money from an Organization with an MMF/WORKING account (B2C, C2B, Merchant HO and store and Agency HO and Store) to an organization with an MMF/WORKING account (B2C, C2B, Merchant HO and store and Agency HO and Store). The organizations should not be in the same Hierarchy. The request moves money from the Primary Party’s MMF/WORKING account to the Receiver party’s MMF/WORKING account. Primary party should be API Enabled Business Customer and receiver party will be an Organization. The initiator would be linked to primary party.
Input Parameters
Amount Decimal
AccountReference String The third party account reference. (optional)
Output Parameters
ResultType ResultType It describes the state of the request, for single staged it would be only completed.
ResultCode String Result code
ResultDesc String Result description
ConversationId GUID M-Pesa conversation id
OriginatorConversationId String Third party conversation id
TransactionId String It takes the financial transaction unique receipt number.
ResultParameters
Amount Decimal The transactional Amount
Eg. <Key>Amount</Key><Value>7000.00</Value>
TransCompletedTime DateTime The date time when the transaction was completed.
Eg. <Key>TransCompletedTime</Key>
<Value>20150424170252</Value>
InitiatorAccountCurrentBalance Decimal Amount of money in the initiating organization.
Eg. <Key>InitiatorAccountCurrentBalance</Key>
<Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value>
DebitPartyCharges Decimal
DebitAccountCurrentBalance Decimal Amount of money in the initiating organization.
Eg. <Key> DebitAccountCurrentBalance </Key>
<Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value>
Currency String Currency used.
Eg. <Key>Currency</Key>
<Value>KES</Value>
DebitPartyPublicName String Public name of the Debit Party.
Format: <Short Code>-<Organization Name>
ReceiverPartyPublicName String Public name of the Credit Party.
Eg. <Key>ReceiverPartyPublicName</Key>
<Value>888888 – KPLC TEST</Value>.
DebitPartyAffectedAccountBalance String Indicates the account balance of all the affected accounts of debit party。
For each account, the fields are presented in the following order and separated by vertical bars (|):
amp; is used as the separator of different accounts.
Eg. <Key>DebitPartyAffectedAccountBalance</Key>
<Value>MMF Organization Account|KES|2714803.00|2714803.00|0.00|50000000.00</Value>

 

BusinessTransferFromMMFToUtility
Description
This is a transaction type that moves money within an Organization (C2B and B2C). The request moves money from the organization’s MMF/WORKING account to the organization’s Utility account. The organization should be API Enabled Business Customer. The initiator would be linked to primary party.
Input Parameters
Amount Decimal
AccountReference String The third party account reference. (optional)
Output Parameters
ResultType ResultType It describes the state of the request, for single staged it would be only completed.
ResultCode String Result code
ResultDesc String Result description
ConversationId GUID M-Pesa conversation id
OriginatorConversationId String Third party conversation id
TransactionId String It takes the financial transaction unique receipt number.
ResultParameters
Amount Decimal The transactional Amount
Eg. <Key>Amount</Key><Value>7000.00</Value>
TransCompletedTime DateTime The date time when the transaction was completed.
Eg. <Key>TransCompletedTime</Key>
<Value>20150424170252</Value>
InitiatorAccountCurrentBalance Decimal Amount of money in the initiating organization.
Eg. <Key>InitiatorAccountCurrentBalance</Key>
<Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value>
DebitPartyCharges Decimal
DebitAccountCurrentBalance Decimal Amount of money in the initiating organization.
Eg. <Key> DebitAccountCurrentBalance </Key>
<Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value>
Currency String Currency used.
Eg. <Key>Currency</Key>
<Value>KES</Value>
DebitPartyPublicName String Public name of the Debit Party.
Format: <Short Code>-<Organization Name>
ReceiverPartyPublicName String Public name of the Credit Party.
Eg. <Key>ReceiverPartyPublicName</Key>
<Value>888888 – KPLC TEST</Value>.
DebitPartyAffectedAccountBalance String Indicates the account balance of all the affected accounts of debit party。
For each account, the fields are presented in the following order and separated by vertical bars (|):
amp; is used as the separator of different accounts.
Eg. <Key>DebitPartyAffectedAccountBalance</Key>
<Value>MMF Organization Account|KES|2714803.00|2714803.00|0.00|50000000.00</Value>

 

BusinessTransferFromUtilityToMMF
Description
This is a transaction type that moves money within an Organization (C2B and B2C). The request moves money from the organization’s Utility account to the organization’s MMF/WORKING account. The organization should be API Enabled Business Customer. The initiator would be linked to primary party
Input Parameters
Amount Decimal
AccountReference String The third party account reference. (optional)
Output Parameters
ResultType ResultType It describes the state of the request, for single staged it would be only completed.
ResultCode String Result code
ResultDesc String Result description
ConversationId GUID M-Pesa conversation id
OriginatorConversationId String Third party conversation id
TransactionId String It takes the financial transaction unique receipt number.
ResultParameters
Amount Decimal The transactional Amount
Eg. <Key>Amount</Key><Value>7000.00</Value>
TransCompletedTime DateTime The date time when the transaction was completed.
Eg. <Key>TransCompletedTime</Key>
<Value>20150424170252</Value>
InitiatorAccountCurrentBalance Decimal Amount of money in the initiating organization.
Eg. <Key>InitiatorAccountCurrentBalance</Key>
<Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value>
DebitPartyCharges Decimal
DebitAccountCurrentBalance Decimal Amount of money in the initiating organization.
Eg. <Key> DebitAccountCurrentBalance </Key>
<Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value>
Currency String Currency used.
Eg. <Key>Currency</Key>
<Value>KES</Value>
DebitPartyPublicName String Public name of the Debit Party.
Format: <Short Code>-<Organization Name>
ReceiverPartyPublicName String Public name of the Credit Party.
Eg. <Key>ReceiverPartyPublicName</Key>
<Value>888888 – KPLC TEST</Value>.
DebitPartyAffectedAccountBalance String Indicates the account balance of all the affected accounts of debit party。
For each account, the fields are presented in the following order and separated by vertical bars (|):
amp; is used as the separator of different accounts.
Eg. <Key>DebitPartyAffectedAccountBalance</Key>
<Value>MMF Organization Account|KES|2714803.00|2714803.00|0.00|50000000.00</Value>

 

MerchantToMerchantTransfer
Description
This is a transaction type that moves money from an Organization with Merchant account (Merchant HO and store) to an organization with a Merchant account (Merchant HO and store). The organizations should not be in the same Hierarchy. The request moves money from the Primary Party’s Merchant account to the Receiver party’s Merchant account. Primary party should be API Enabled Business Customer and receiver party will be an Organization. The initiator would be linked to primary party.
Input Parameters
Amount Decimal
AccountReference String The third party account reference. (optional)
Output Parameters
ResultType ResultType It describes the state of the request, for single staged it would be only completed.
ResultCode String Result code
ResultDesc String Result description
ConversationId GUID M-Pesa conversation id
OriginatorConversationId String Third party conversation id
TransactionId String It takes the financial transaction unique receipt number.
ResultParameters
Amount Decimal The transactional Amount
Eg. <Key>Amount</Key><Value>7000.00</Value>
TransCompletedTime DateTime The date time when the transaction was completed.
Eg. <Key>TransCompletedTime</Key>
<Value>20150424170252</Value>
InitiatorAccountCurrentBalance Decimal Amount of money in the initiating organization.
Eg. <Key>InitiatorAccountCurrentBalance</Key>
<Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value>
DebitPartyCharges Decimal
DebitAccountCurrentBalance Decimal Amount of money in the initiating organization.
Eg. <Key> DebitAccountCurrentBalance </Key>
<Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value>
Currency String Currency used.
Eg. <Key>Currency</Key>
<Value>KES</Value>
DebitPartyPublicName String Public name of the Debit Party.
Format: <Short Code>-<Organization Name>
ReceiverPartyPublicName String Public name of the Credit Party.
Eg. <Key>ReceiverPartyPublicName</Key>
<Value>888888 – KPLC TEST</Value>.
DebitPartyAffectedAccountBalance String Indicates the account balance of all the affected accounts of debit party。
For each account, the fields are presented in the following order and separated by vertical bars (|):
amp; is used as the separator of different accounts.
Eg. <Key>DebitPartyAffectedAccountBalance</Key>
<Value>MMF Organization Account|KES|2714803.00|2714803.00|0.00|50000000.00</Value>

 

MerchantTransferFromMerchantToWorking
Description
This is a transaction type that moves money within an Organization (Merchant HO and Store). The request moves money from the organization’s Merchant account to the organization’s MMF/WORKING account. The organization should be API Enabled Business Customer. The initiator would be linked to primary party
Input Parameters
Amount Decimal
AccountReference String The third party account reference. (optional)
Output Parameters
ResultType ResultType It describes the state of the request, for single staged it would be only completed.
ResultCode String Result code
ResultDesc String Result description
ConversationId GUID M-Pesa conversation id
OriginatorConversationId String Third party conversation id
TransactionId String It takes the financial transaction unique receipt number.
ResultParameters
Amount Decimal The transactional Amount
Eg. <Key>Amount</Key><Value>7000.00</Value>
TransCompletedTime DateTime The date time when the transaction was completed.
Eg. <Key>TransCompletedTime</Key>
<Value>20150424170252</Value>
InitiatorAccountCurrentBalance Decimal Amount of money in the initiating organization.
Eg. <Key>InitiatorAccountCurrentBalance</Key>
<Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value>
DebitPartyCharges Decimal
DebitAccountCurrentBalance Decimal Amount of money in the initiating organization.
Eg. <Key> DebitAccountCurrentBalance </Key>
<Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value>
Currency String Currency used.
Eg. <Key>Currency</Key>
<Value>KES</Value>
DebitPartyPublicName String Public name of the Debit Party.
Format: <Short Code>-<Organization Name>
ReceiverPartyPublicName String Public name of the Credit Party.
Eg. <Key>ReceiverPartyPublicName</Key>
<Value>888888 – KPLC TEST</Value>.
DebitPartyAffectedAccountBalance String Indicates the account balance of all the affected accounts of debit party。
For each account, the fields are presented in the following order and separated by vertical bars (|):
amp; is used as the separator of different accounts.
Eg. <Key>DebitPartyAffectedAccountBalance</Key>
<Value>MMF Organization Account|KES|2714803.00|2714803.00|0.00|50000000.00</Value>

 

MerchantTransferFromWorkingToMerchant
Description
This is a transaction type that moves money within an Organization (Merchant HO and Store). The request moves money from the organization’s MMF/WORKING account to the organization’s Merchant account. The organization should be API Enabled Business Customer. The initiator would be linked to primary party.
Input Parameters
Amount Decimal
AccountReference String The third party account reference. (optional)
Output Parameters
ResultType ResultType It describes the state of the request, for single staged it would be only completed.
ResultCode String Result code
ResultDesc String Result description
ConversationId GUID M-Pesa conversation id
OriginatorConversationId String Third party conversation id
TransactionId String It takes the financial transaction unique receipt number.
ResultParameters
Amount Decimal The transactional Amount
Eg. <Key>Amount</Key><Value>7000.00</Value>
TransCompletedTime DateTime The date time when the transaction was completed.
Eg. <Key>TransCompletedTime</Key>
<Value>20150424170252</Value>
InitiatorAccountCurrentBalance Decimal Amount of money in the initiating organization.
Eg. <Key>InitiatorAccountCurrentBalance</Key>
<Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value>
DebitPartyCharges Decimal
DebitAccountCurrentBalance Decimal Amount of money in the initiating organization.
Eg. <Key> DebitAccountCurrentBalance </Key>
<Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value>
Currency String Currency used.
Eg. <Key>Currency</Key>
<Value>KES</Value>
DebitPartyPublicName String Public name of the Debit Party.
Format: <Short Code>-<Organization Name>
ReceiverPartyPublicName String Public name of the Credit Party.
Eg. <Key>ReceiverPartyPublicName</Key>
<Value>888888 – KPLC TEST</Value>.
DebitPartyAffectedAccountBalance String Indicates the account balance of all the affected accounts of debit party。
For each account, the fields are presented in the following order and separated by vertical bars (|):
amp; is used as the separator of different accounts.
Eg. <Key>DebitPartyAffectedAccountBalance</Key>
<Value>MMF Organization Account|KES|2714803.00|2714803.00|0.00|50000000.00</Value>

 

OrgBankAccountWithdrawal
Description
This is a transaction type that moves money from an Organization (C2B, B2C, Agency and Merchant) to the Bank. The request removes e-value from the MMF/Working account to the SP holding account. The organization should be API Enabled Business Customer. The initiator would be linked to primary party.
Input Parameters
Amount decimal Value to be transferred
HeadOffice String Optional
Output Parameters
ResultType ResultType It describes the state of the request, for single staged it would be only completed.
ResultCode String Result code
ResultDesc String Result description
ConversationId GUID M-Pesa conversation id
OriginatorConversationId String Third party conversation id
TransactionId String It takes the financial transaction unique receipt number.
ResultParameters
Amount Decimal The transactional Amount
Eg. <Key>Amount</Key><Value>7000.00</Value>
TransCompletedTime DateTime The date time when the transaction was completed.
Eg. <Key>TransCompletedTime</Key>
<Value>20150424170252</Value>
DebitPartyAffectedAccountBalance String Indicates the account balance of all the affected accounts of debit party。
For each account, the fields are presented in the following order and separated by vertical bars (|):
amp; is used as the separator of different accounts.
Eg. <Key>DebitPartyAffectedAccountBalance</Key>
<Value>MMF Organization Account|KES|2714803.00|2714803.00|0.00|50000000.00</Value>

 

OrgRevenueSettlement
Description
This is a transaction type that moves money within an Organization (C2B and Merchant). The request settles the charges accrued and moves the rest of the money to the MMF/Working account. The organization should be API Enabled Business Customer. The initiator would be linked to primary party.
Input Parameters
HeadOffice String Optional
Output Parameters
ResultType ResultType It describes the state of the request, for single staged it would be only completed.
ResultCode String Result code
ResultDesc String Result description
ConversationId GUID M-Pesa conversation id
OriginatorConversationId String Third party conversation id
TransactionId String It takes the financial transaction unique receipt number.
ResultParameters
FundsMovement Decimal Describes the Fund movement.
Eg. <Key>FundsMovement</Key>
<Value>Merchant Account|Organization Settlement Account|KES|0.00&Organization Settlement Account|Charges Paid Account|KES|0.00&Working Account|Organization Settlement Account|KES|0.00</Value>
TransCompletedTime DateTime The date time when the transaction was completed.
Eg. <Key>TransCompletedTime</Key>
<Value>20150424170252</Value>
AccountBalanceAfterSettlement Decimal Amount of money in the organization.
Eg. <Key>AccountBalanceAfterSettlement</Key>
<Value>Working Account|KES|56.03|56.03|0.00|0.00&Utility Account|KES|0.00|0.00|0.00|0.00&Charges Paid Account|KES|0.00|0.00|0.00|0.00&Merchant Account|KES|0.00|0.00|0.00|0.00&Organization Settlement Account|KES|0.00|0.00|0.00|0.00</Value>
SettlementPlanID Decimal This field gives the settlementID.
Eg. <Key>SettlementPlanID</Key>
<Value>172110</Value>

 

MerchantServicesMMFAccountTransfer
Description
This is a transaction type that moves money from an Organization with Merchant account (Merchant HO and store) to an organization with a Merchant account (Merchant HO and store). The organizations should be in the same Hierarchy. The request moves money from the Primary Party’s Merchant account to the Receiver party’s Merchant account. Primary party should be API Enabled Business Customer and receiver party will be an Organization. The initiator would be linked to primary party.
Input Parameters
Amount Decimal
AccountReference String The third party account reference. (optional)
Output Parameters
ResultType ResultType It describes the state of the request, for single staged it would be only completed.
ResultCode String Result code
ResultDesc String Result description
ConversationId GUID M-Pesa conversation id
OriginatorConversationId String Third party conversation id
TransactionId String It takes the financial transaction unique receipt number.
ResultParameters
Amount Decimal The transactional Amount
Eg. <Key>Amount</Key><Value>7000.00</Value>
TransCompletedTime DateTime The date time when the transaction was completed.
Eg. <Key>TransCompletedTime</Key>
<Value>20150424170252</Value>
InitiatorAccountCurrentBalance Decimal Amount of money in the initiating organization.
Eg. <Key>InitiatorAccountCurrentBalance</Key>
<Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value>
DebitPartyCharges Decimal
DebitAccountCurrentBalance Decimal Amount of money in the initiating organization.
Eg. <Key> DebitAccountCurrentBalance </Key>
<Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value>
Currency String Currency used.
Eg. <Key>Currency</Key>
<Value>KES</Value>
DebitPartyPublicName String Public name of the Debit Party.
Format: <Short Code>-<Organization Name>
ReceiverPartyPublicName String Public name of the Credit Party.
Eg. <Key>ReceiverPartyPublicName</Key>
<Value>888888 – KPLC TEST</Value>.
DebitPartyAffectedAccountBalance String Indicates the account balance of all the affected accounts of debit party。
For each account, the fields are presented in the following order and separated by vertical bars (|):
amp; is used as the separator of different accounts.
Eg. <Key>DebitPartyAffectedAccountBalance</Key>
<Value>MMF Organization Account|KES|2714803.00|2714803.00|0.00|50000000.00</Value>

 

AgencyFloatAdvance
Description
This is a transaction type that moves money from an Organization with a Float account (Agency HO and store) to an organization with a Float account (Agency HO and store). The organizations should not be in the same Hierarchy. The request moves money from the Primary Party’s Float account to the Receiver party’s Float account. Primary party should be API Enabled Business Customer and receiver party will be an Organization. The initiator would be linked to primary party.
Input Parameters
Amount Decimal
AccountReference String The third party account reference. (optional)
Output Parameters
ResultType ResultType It describes the state of the request, for single staged it would be only completed.
ResultCode String Result code
ResultDesc String Result description
ConversationId GUID M-Pesa conversation id
OriginatorConversationId String Third party conversation id
TransactionId String It takes the financial transaction unique receipt number.
ResultParameters
Amount Decimal The transactional Amount
Eg. <Key>Amount</Key><Value>7000.00</Value>
TransCompletedTime DateTime The date time when the transaction was completed.
Eg. <Key>TransCompletedTime</Key>
<Value>20150424170252</Value>
InitiatorAccountCurrentBalance Decimal Amount of money in the initiating organization.
Eg. <Key>InitiatorAccountCurrentBalance</Key>
<Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value>
DebitPartyCharges Decimal
DebitAccountCurrentBalance Decimal Amount of money in the initiating organization.
Eg. <Key> DebitAccountCurrentBalance </Key>
<Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value>
Currency String Currency used.
Eg. <Key>Currency</Key>
<Value>KES</Value>
DebitPartyPublicName String Public name of the Debit Party.
Format: <Short Code>-<Organization Name>
ReceiverPartyPublicName String Public name of the Credit Party.
Eg. <Key>ReceiverPartyPublicName</Key>
<Value>888888 – KPLC TEST</Value>.
DebitPartyAffectedAccountBalance String Indicates the account balance of all the affected accounts of debit party。
For each account, the fields are presented in the following order and separated by vertical bars (|):
amp; is used as the separator of different accounts.
Eg. <Key>DebitPartyAffectedAccountBalance</Key>
<Value>MMF Organization Account|KES|2714803.00|2714803.00|0.00|50000000.00</Value>

 

Balance Query from the Business Customer
Description
This is a new request to check a Balance for the associated Business Customer. In case the initiator is associated to the Merchant HO, it can request a balance query of merchant store within the hierarchy. No financial transaction would be created. It will just respond back with the balance within the account at the time of request.
Input Parameters
ShortCode Integer The short code associated to the business or store.
OrgShortCodeList String List of short code of the organizations whose balances need to be checked. Each short code must be delimited by ;
The total number of short codes in the list must not exceed the Maximum configured in the system.(Optional)
AccountType String The account type alias in the M-Pesa system for querying balance.
If this parameter is absent, the balance of all accounts will be returned in the Result. (Optional)
Output Parameters
ResultType ResultType It describes the state of the request, for single staged it would be only completed.
ResultCode String Response code
ResultDescription String Response description
ConversationId GUID M-Pesa conversation id
OriginatorConversationId String Third party conversation id
ResultParameters
ShortCode String The organisation short code for which the balance request is performed
OrganisationName String The organisation name associated to the short code.
Account Balance SetTime DateTime The date time when the balance was last updated.
Account Number String The M-Pesa generated account number which can be viewed on the identity page.
Working Account Available Funds Decimal Mmf account available balance.
Working Account Uncleared Funds Decimal Mmf account uncleared balance.
Working Account Reserved Funds Decimal Mmf account reserved balance.
Charges Paid Account Available Funds Decimal Charge paid account available balance
Charges Paid Account Uncleared Funds Decimal Charge paid account uncleared balance
Charges Paid Account Reserved Funds Decimal Charge paid account reserved balance
Utility Account Available Funds Decimal Utility account available balance
Utility Account Uncleared Funds Decimal Utility account uncleared balance
Utility Account Reserved Funds Decimal Utility account reserved balance
BOCompletedTime String The data time when the business operation was completed, as recorded in the M-Pesa system.
Format: YYYYMMDDhhmmss
AccountBalance String Indicates the accounts balance of organizations to be queried.
For each account, the fields are presented in the following order and separated by vertical bars (|):
Format: <Account Type Alias>|<Currency>|<Current Balance>|<Available Balance>|<Reserved Balance>|<Unclear Balance>
&amp; is used as the separator of different accounts.
For each organization, a short code will be added before the accounts, separated by vertical bars (|):
Format: <Shot Code> |<Account 1 Balance>| <Account 2 Balance>|…
#; is used as the separator of a different organization
In case, when failed to query one of the organization, such as:
ü  No organization is found by the organization short code
ü  This organization is not a sub-organization of the initiator
The system will return:
Format: <Shot Code> |Failed

 

Transaction Status Query
Description
It is a new request to make a transaction status inquiry. All the initiator or caller can perform this request to check the transaction status of the already performed request.
Input Parameters
OriginatorConversationID String Pass one of these parameter to search for the transaction. In case the transaction is older than 15 days use only ReceiptNumber to search for the transaction status. It wont return any result in case OriginatorConversationID or ConversationID is used.
ConversationID String Pass one of these parameter to search for the transaction. In case the transaction is older than 15 days use only ReceiptNumber to search for the transaction status. It wont return any result in case OriginatorConversationID or ConversationID is used.
ReceiptNumber String Pass one of these parameter to search for the transaction. In case the transaction is older than 15 days use only ReceiptNumber to search for the transaction status. It wont return any result in case OriginatorConversationID or ConversationID is used.
Output Parameters
ResultType ResultType It mentions the state of the transaction. If successfully done it would say Completed
ResultCode string Response code
ResultDescription String Response description
ConversationId GUID M-Pesa conversation id
OriginatorConversationId String Third party conversation id
ResultParameters
InitiatedTime Datetime Transaction initiated Time.
FinalisedTime Datetime Transaction Finalised Time
TransactionType String Transaction type associated to the receipt number
ReceiptNo String Transaction ReceiptNo
TransactionStatus String Transaction status outcome
TransactionReason String Transaction reason in case of decline
DebitPartyName String Debit party identity name
CreditPartyName String Credit party identity name
DebitAccountType String Debit party account type
DebitAccountBalance Decimal Debit party account balance
ReasonType String
Originator Conversation ID String
Conversation ID String
Amount String
DebitPartyCharges String
CreditPartyCharges String

 

Examples


Sample API Call To Broker

<soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:req=”http://api-v1.gen.mm.vodafone.com/mminterface/request”>
<soapenv:Header>
<tns:RequestSOAPHeader xmlns:tns=”http://www.huawei.com/schema/osg/common/v2_1″>
<tns:spId>107043</tns:spId>
<tns:spPassword>encrypted_spPassword</tns:spPassword>
<tns:timeStamp>yyyymmddhhmmss</tns:timeStamp>
<tns:serviceId>107043000</tns:serviceId>
</tns:RequestSOAPHeader>
</soapenv:Header>
<soapenv:Body>
<req:RequestMsg>
<![CDATA[<?xml version=’1.0′ encoding=’UTF-8′?>
<Request xmlns=”http://api-v1.gen.mm.vodafone.com/mminterface/request”>
<Transaction>
<CommandID>BusinessPayBill</CommandID>
<LanguageCode></LanguageCode>
<OriginatorConversationID>111111org0123456789</OriginatorConversationID>
<ConversationID></ConversationID>
<Remark></Remark>
<Parameters>
<Parameter>
<Key>Amount</Key>
<Value>1500.00</Value>
</Parameter>
<Parameter>
<Key>AccountReference</Key>
<Value>0123456789</Value>
</Parameter>
</Parameters>
<ReferenceData><ReferenceItem>
<Key>QueueTimeoutURL</Key>
<Value>https://11.11.11.11:443/timeout</Value>
</ReferenceItem></ReferenceData>
<Timestamp>2014-09-22T14:10:47.220+03:00</Timestamp>
</Transaction>
<Identity>
<Caller>
<CallerType>2</CallerType>
<ThirdPartyID></ThirdPartyID>
<Password></Password>
<CheckSum></CheckSum>
<ResultURL>https://11.11.11.11:443/Result</ResultURL>
</Caller>
<Initiator>
<IdentifierType>11</IdentifierType>
<Identifier>initiator</Identifier>
<SecurityCredential>encypted_initiator_password</SecurityCredential>
<ShortCode>111111</ShortCode>
</Initiator>
<PrimaryParty>
<IdentifierType>4</IdentifierType>
<Identifier>111111</Identifier>
<ShortCode></ShortCode>
</PrimaryParty>
<ReceiverParty>
<IdentifierType>4</IdentifierType>
<Identifier>222222</Identifier>
<ShortCode></ShortCode>
</ReceiverParty>
<AccessDevice>
<IdentifierType></IdentifierType>
<Identifier></Identifier>
</AccessDevice>
</Identity>
<KeyOwner>1</KeyOwner>
</Request>]]></req:RequestMsg>
</soapenv:Body>
</soapenv:Envelope>

Sample API Response To 3rd Party

<soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/”>
<soapenv:Body>
<req:ResponseMsg xmlns:req=”http://api-v1.gen.mm.vodafone.com/mminterface/request”><![CDATA[<?xml version=”1.0″ encoding=”UTF-8″?>
<response xmlns=”http://apiv1.gen.mm.vodafone.com/mminterface/response”>
<ResponseCode>0</ResponseCode><ConversationID>AG_20150424_0000626ec4aeb2ca2256</ConversationID>
<ResponseDesc>service request accepted successfully.</ResponseDesc>
<OriginatorConversationID>111111org0123456789</OriginatorConversationID>
<ServiceStatus>0</ServiceStatus>
</response>]]></req:ResponseMsg>
</soapenv:Body>
</soapenv:Envelope>

Sample API Result To 3rd Party

<soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/”>
<soapenv:Body>
<res:ResultMsg xmlns:res=”http://api-v1.gen.mm.vodafone.com/mminterface/result”><![CDATA[<?xml version=”1.0″ encoding=”UTF-8″?><Result xmlns=”http://api-v1.gen.mm.vodafone.com/mminterface/result”>
<ResultType>0</ResultType><ResultCode>0</ResultCode><ResultDesc>Accept the service requestsuccessfully.</ResultDesc>
<OriginatorConversationID>111111org0123456789</OriginatorConversationID><ConversationID>AG_20150424_0000643cae726da52ba8</ConversationID>
<TransactionID>JDO71LM99</TransactionID>
<ResultParameters>
<ResultParameter><Key>InitiatorAccountCurrentBalance</Key><Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value></ResultParameter><ResultParameter><Key>DebitAccountCurrentBalance</Key><Value>{Amount={BasicAmount=2714803.00, MinimumAmount=271480300, CurrencyCode=KES}}</Value></ResultParameter><ResultParameter><Key>Amount</Key><Value>7000.00</Value></ResultParameter><ResultParameter><Key>DebitPartyAffectedAccountBalance</Key><Value>MMF Organization Account|KES|2714803.00|2714803.00|0.00|50000000.00</Value></ResultParameter><ResultParameter><Key>TransCompletedTime</Key><Value>20150424170252</Value></ResultParameter><ResultParameter><Key>DebitPartyCharges</Key><Value></Value></ResultParameter><ResultParameter><Key>ReceiverPartyPublicName</Key><Value>888888 – KPLC TEST</Value></ResultParameter><ResultParameter><Key>CreditPartyAffectedAccountBalance</Key><Value>Utility Account|KES|11000.00|11000.00|0.00|0.00&Charges Paid Account|KES|-385.00|-385.00|0.00|0.00</Value></ResultParameter><ResultParameter><Key>CreditAccountCurrentBalance</Key><Value>{Amount={BasicAmount=11000.00, MinimumAmount=1100000, CurrencyCode=KES}}</Value></ResultParameter><ResultParameter><Key>Currency</Key><Value>KES</Value></ResultParameter>
</ResultParameters>
<ReferenceData><ReferenceItem><Key>BillReferBillReferenceNumber</Key><Value>7000</Value></ReferenceItem><ReferenceItem><Key>QueueTimeoutURL</Key><Value>http://10.66.49.201:</Value></ReferenceItem>
</ReferenceData></Result>]]>
</res:ResultMsg>
</soapenv:Body>
</soapenv:Envelope>

Sample API response From 3rd Party

<soap:Envelope xmlns:soap=”http://schemas.xmlsoap.org/soap/envelope/”>
<soap:Body>
<ns2:ResponseMsg xmlns:ns2=”http://api-v1.gen.mm.vodafone.com/mminterface/result”>
<![CDATA[<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<response xmlns=”http://api-v1.gen.mm.vodafone.com/mminterface/response”>
<ResponseCode>00000000</ResponseCode>
<ResponseDesc>success</ResponseDesc>
<ConversationID></ConversationID>
<OriginatorConversationID></OriginatorConversationID>
<ServiceStatus></ServiceStatus>
</response>]]>
</ns2:ResponseMsg>
</soap:Body>
</soap:Envelope>