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 |
|
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 |
NOTE: The value |
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 |
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 These are both returned by the |
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 |
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 |
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 |
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 |
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 |
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 |
20 | UnresolvedInitiator The initiator username presented with the request cannot be found. This is included in the |
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 |
22 | InitiatorStatusCheckFailure The presented initiator username can be received, but the initiator is not currently active. This fact is returned in the |
23 | RequestSchemaValidationError Incoming API requests are validated against the schema defined in |
24 | MissingRequestParameters Required input parameters are defined for each type of API operation. If these are missing, then this is issued in the |
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 |
26 | SystemTooBusy Included in the |
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 |
29 | InvalidCommand The command specified in the request is not defined – this is part of the |
30 | ErrorSerializingRequest After XML schema validation, the API attempts to convert the XML request into an internal ApiRequest object – any failures result in this |
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 |
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 |
38 | InvalidConversationId |
39 | UnknownConversationId Not currently checked for – this will take place for multi-stage conversations. |
40 | InvalidParameterDefinition |