3.1 IdentityType enumeration

List of IdentityType values.

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

3.2 IdentifierType enumeration

List of IdentityType values.

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

3.3 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.

3.4 Parameters structure

Element name Element type Optional Description
Parameter ParameterTyp e[1..unbounde d] No It is used to carry specific parameters for specific transaction or business operation.

3.5 ReferenceData structure

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

3.6 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.
OriginatorConv ersationID 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.

3.7 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 he 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.

3.8 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.

3.8.1 Password Encryption

The Caller will be required to confirm its authority to act on behalf of the Initiator (in other words, 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:

First, create the block of data to be encrypted:

  • Write the unencrypted password value.
  • Then, encrypt the block of data created in step 1 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 – this becomes the encrypted password which is submitted via the API.
  • 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.

3.9 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

3.10 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.

3.11 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

3.12 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:
  • SP operator
  • Organizationoperator(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.

3.13 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

3.14 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:string Yes It indicates the MM service status.

3.15 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.

3.16 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

3.17 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

%1 indicates the parameter’s name.

ApiResponse
100000006 SP’s status is abnormal ApiResponse
100000007 Authentication failed ApiResponse
100000008 Service’s status is abnormal 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

%1 indicates the parameter’s name.

ApiResponse

The following table lists result codes and result descriptions which are provided to the third party. These may be commincated either in the synchronous ApiResponse message, or in the asynchronous ApiResult message.

0

Success

This is indicated for both ApiResponse and ApiResult messages. An ApiResponse value of 0 indicates that the request has passed basic validation tests and been passed on to the core system for further processing. An ApiResult value of 0 means that the requested financial transaction has been completed successfully.

1

InsufficientFunds

Typically indicates that the primary party does not have enough money to complete the requested financial transaction. In the case of the B2C API, this means that the business organisation does not have enough money in its utility account.

This is returned by the ApiResult and represented internally as a transaction reason.

2 LessThanMinimumTransactionValue
3

MoreThanMaximumTransactionValue

Each of these potential failures derive from the rules which govern MPesa financial transactions. In the case of the B2C API, these are taken from DefaultBusinessUtilityAccount rules, which specify a lower bound of 10 KE shillings and an upper bound of 70000. For promotion payments and salary payments to unregistered users, the upper limit is lower: 35000. Likewise, the lower bound for these 2 transactions is also different: 101 rather than 10.

These are both returned by the ApiResult and represented internally as a transaction reason.

4

WouldExceedDailyTransferLimit

This is a limit on daily activity. For the business organisation, this is very high: 100000000 KE shillings. It is much more likely that this rule will apply to the customer, where the limit is 140000 KE shillings.

This is returned by the ApiResult and represented internally as a transaction reason.

5

WouldExceedMinimumBalance

This rule is rather confusingly named – it actually means that a transaction would bring the business organisations utility account bellow the required minimum – which is currently 0.

This is returned by the ApiResult and represented internally as a transaction reason. It is computed during execution of the financial transaction.

6 UnresolvedPrimaryParty
7

UnresolvedReceiverParty

The primary party or receiver party cannot be associated with an MPesa identity. For transactions (such as promotion payment and salary payment) which are supported for unregistered users, the unresolved receiver party rule is not applied.

These are returned in the ApiResult and checked before the linked financial transaction is created.

8

WouldExceedMaximumBalance

For the B2C API, this applies to the recipient MMF customer – the limit here is 100,000 KE shillings.

This is returned by the ApiResult and represented internally as a transaction reason. It is computed during execution of the financial transaction.

9 LessThanMinAirtimeValue
10

MoreThanMaxAirtimeValue

Neither of these apply to B2C API operations.

11 DebitAccountInvalid
12 CreditAccountInvalid
13 UnresolvedDebitAccount
14

UnresolvedCreditAccount

These are all existing failure transaction reasons for B2C financial transactions – they would be issued to the caller in the ApiResult message. The latter 2 in particular are unlikely to occur, as the request would be rejected by Core API specific checks before the request reached the accounting engine.

15

DuplicateDetected

Currently, any requests which presents an originator conversation id which has been seen before will be rejected. This rule will need to be reconsidered in contexts which require multi-stage conversations or multiple Callers. This check (along with the message expiry check) is the first thing done by the transaction processor when handling an API request. The outcome is reported in the ApiResult message.

16

PayUtilityInvalidAccountNumberFormat

Does not apply to the B2C API operations.

17

InternalFailure

A catch all for failures which are not identified more specifically – this can occur in either the ApiResponse or ApiResult – although the intent is to replace any such error with a more precise message.

18

InitiatorCredentialCheckFailure

The password check for the initiator failed, either because the presented password is wrong, or something has gone wrong in the encryption or decryption steps. This is issued in the ApiResult before the creation of a financial transaction.

19

ApiRequestMessageExpiryFailure

Initiators have the option to specify a request timestamp. If the gap between this value and the time at which the message is received by the transaction processor is too great, then the request is rejected. The specific interval is configured separately for each API operation (and indeed, for each API operation stage). This is the first check performed on an API request arriving at the transaction processor, and as such is included in the ApiResult message.

20

UnresolvedInitiator

The initiator username presented with the request cannot be found. This is included in the ApiResult.

21

InitiatorToPrimaryPartyPermissionFailure

The initiator presented does not have the right to issue requests for the specified primary party (as established during creation of the initiator on the admin web site). The is part of the ApiResult, and computed prior to issuing a financial transaction.

22

InitiatorStatusCheckFailure

The presented initiator username can be received, but the initiator is not currently active. This fact is returned in the ApiResult.

23

RequestSchemaValidationError

Incoming API requests are validated against the schema defined in CPSInterface_Request.xsd. This is part of the ApiResponse message – the details of the validation error are included in the response.

24

MissingRequestParameters

Required input parameters are defined for each type of API operation. If these are missing, then this is issued in the ApiResult message. The names of the missing parameters are included in the result parameters field.

25

InvalidRequestParameters

If all required parameters are presented, then validation checks are performed. Specifically, the parameter is checked to see if it can be converted to the intended type, and then checked against (optional) configuration regular expression based validation rules. For the B2C API, only the type check (i.e the amount specified is a valid decimal) is performed. Failures are indicated in the ApiResult message, with the details included in the result parameters.

26

SystemTooBusy

Included in the ApiResponse message if a traffic blocking condition is in place. See section 5.1 for more detail.

28

InitiatorAllowedOperationCheckFailure

Upon creation, initiators are assigned permissions for specific API operations – if the operation specified in the request message is not included in this list, then this ApiResult message is received.

29

InvalidCommand

The command specified in the request is not defined – this is part of the ApiResult.

30

ErrorSerializingRequest

After XML schema validation, the API attempts to convert the XML request into an internal ApiRequest object – any failures result in this ApiResponse message. The details of the exception are included.

31

InitiatorNotSpecified

The initiator username is not specified, or not specified in a way that can be parsed.

32

ErrorSerializingRequest

The presented identifier for the initiator is not a username.

33 PrimaryPartyNotSpecified
34 PrimaryPartyIdentifierInvalid
35 ReceiverPartyNotSpecified
36

ReceiverPartyIdentifierInvalid

In all these case, one of the API parties is either missing from the request, or has been presented with the wrong identifier type., This kind of failure is indicated in the ApiResult message.

37

MissingApiCommand

No command is included in the request – in general this problem should be captured by the XML schema validation, but if it is not this ApiResult message is issued.

38 InvalidConversationId
39

UnknownConversationId

Not currently checked for – this will take place for multi-stage conversations.

40 InvalidParameterDefinition