PROJECT NAME: M-PESA G2
DOCUMENT NAME: DEVELOPERS GUIDE- PAYBILL
VALIDATION AND CONFIRMATION
VERSION: 0.3
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT
DATE: 3RD AUGUST 2015
Developers Guide
PayBill Validation and Confirmation
Version 0.3
PROJECT NAME: M-PESA G2
DOCUMENT NAME: DEVELOPERS GUIDE- PAYBILL
VALIDATION AND CONFIRMATION
VERSION: 0.3
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT
DATE: 3RD AUGUST 2015
Document Control
1.1 Document History
VERSION
STATUS
DATE
CHANGE SUMMARY
OWNER/AUTHOR
0.1
Draft
2014-10-07
First Draft
Wambugu Clement
0.2
Draft
2015-02-28
Added Buygoods definition and
Broker account details
Eneth Kubai
0.3
Draft
2015-08-03
Added the response codes for
Validation response
Eneth Kubai
PROJECT NAME: M-PESA G2
DOCUMENT NAME: DEVELOPERS GUIDE- PAYBILL
VALIDATION AND CONFIRMATION
VERSION: 0.3
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT
DATE: 3RD AUGUST 2015
1.2 Stakeholder & Review Panel
NAME
ROLE
Mark Mumo
SFC BA
Eneth Kubai
SFC BA
Wambugu Clement
SFC BA
PROJECT NAME: M-PESA G2
DOCUMENT NAME: DEVELOPERS GUIDE- PAYBILL
VALIDATION AND CONFIRMATION
VERSION: 0.3
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT
DATE: 3RD AUGUST 2015
Contents
Table of Contents
1 Document Control........................................................................2
1.1 Document History................................................................................................... 2
1.2 Stakeholder & Review Panel....................................................................................3
2 Contents..................................................................................... 4
3 Overview..................................................................................... 5
3.1.1 Background....................................................................................................... 5
3.1.2 Service Flow...................................................................................................... 5
4 Interface Specification.................................................................7
4.1 PayBill Transaction Validation and Confirmation.....................................................7
4.1.1 PayBill Transaction Validation Request from M-Pesa to Broker..........................7
4.1.2 PayBill Transaction Validation Result from Broker to M-Pesa.............................9
4.1.3 PayBill Transaction Confirmation Request from M-Pesa to Broker...................10
4.1.4 PayBill Transaction Confirmation Result from Broker to M-Pesa......................12
4.2 RegisterURL.......................................................................................................... 13
4.2.1 RegisterURL interface specification.................................................................13
5 Annex.......................................................................................19
PROJECT NAME: M-PESA G2
DOCUMENT NAME: DEVELOPERS GUIDE- PAYBILL
VALIDATION AND CONFIRMATION
VERSION: 0.3
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT
DATE: 3RD AUGUST 2015
Overview
3.1.1 Background
When a customer initiates a Pay Bill service, the system will firstly authorize the transaction (reserve funds) and
then sends a validation message to the bill issuer or merchant origination via API. The transaction will only be
successful when the third party validation is passed, otherwise it will be cancelled or be kept in Authorized
status.
When the transaction is successfully completed in the Mobile Money system, another confirmation message will
also be sent to the third parties for real-time reconciliation. The confirmation request will be sent for both Buy
goods and Paybill transactions.
3.1.2 Service Flow
The service flow for this interface shall be as follows
PROJECT NAME: M-PESA G2
DOCUMENT NAME: DEVELOPERS GUIDE- PAYBILL
VALIDATION AND CONFIRMATION
VERSION: 0.3
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT
DATE: 3RD AUGUST 2015
3.1.2.1
PayBill Transaction Validation and Confirmation
A customer PayBill transaction can be initiated via STK or API channel. The transaction request will be sent the
M-Pesa system for processing.
After the M-Pesa system authorizes the transaction, an external transaction validation request will be sent to 3 rd
Party system via Broker. The external transaction validation is optional.
If the correct response (the Result Code parameter from the third party value is 0) is received from the Broker, the
Mobile Money system will complete the corresponding payment transaction. The transaction status will be
changed to Completed.
If error response is replied by the Broker (the Result Code parameter from the third party value is not 0), the
Mobile Money system will cancel the corresponding payment transaction. The transaction status will be changed
to Cancelled.
The third party shall be registered in the broker, and must provide a callback URL for the Confirmation and the
Validation and a default response when they are unreachable for the validation. This interface is described in the
RegisterURL interface specification below.
After the validation, the M-Pesa system will complete the transaction. When the transaction is completed, besides
SMS notifications will be sent to the Customer, a transaction confirmation message will also be sent to the Third
Party system via Broker. The Third party system will capture the transactions from the confirmation message.
6
PROJECT NAME: M-PESA G2
DOCUMENT NAME: DEVELOPERS GUIDE- PAYBILL
VALIDATION AND CONFIRMATION
VERSION: 0.3
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT
DATE: 3RD AUGUST 2015
The confirmation message has no effect in the processing of the transaction.
PROJECT NAME: M-PESA G2
DOCUMENT NAME: DEVELOPERS GUIDE- PAYBILL
VALIDATION AND CONFIRMATION
VERSION: 0.3
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT
DATE: 3RD AUGUST 2015
Interface Specification
4.1 PayBill Transaction Validation and
Confirmation
4.1.1 PayBill Transaction Validation Request from M-Pesa to
Broker
The detail of C2BPaymentValidationRequest message from M-Pesa to Broker describes as following:
SN Field Name
Type
Example
value
Optiona
Description
l
TransType
String
PayBill
No
TransID
String
12345600000070 No
The Transaction Type name of the
BuyGoods transaction.
The unique identifier of the payment
8
PROJECT NAME: M-PESA G2
DOCUMENT NAME: DEVELOPERS GUIDE- PAYBILL
VALIDATION AND CONFIRMATION
VERSION: 0.3
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT
DATE: 3RD AUGUST 2015
31
TransTime
String
YYYYMMDDhh
mmss
transaction that is generated by M-Pesa
system.
No
The date and time when customer
initiates a Buy Goods transaction.
No
The amount of the transaction. Two
decimals fixed point number. Fixed
Currency Type: KES e.g. 123.00 stands
for: 123.00 Ksh
No
The organization short code of the
Merchant in the M-Pesa system
20140227082020
123.00
4
TransAmount
String
BusinessShortCode String
BillRefNumber
String
InvoiceNumber
String
MSISDN
String
12345
TX1001
Yes
X334343
Yes
254722703614
No
This field is not applicable for Buy
Goods transactions. It will always be
blank.
Invoice Number as Entered by Identity
This field is reserved. It will always be
blank in current delivery.
The customers MSISDN, which is with
country code prefix.
The customers KYC information, maybe
multiple KYC info.
KYCInfo
9
KYCName
String
[Personal Details]
Yes
[First Name]
This KYC indicates the customers first
name
10
KYCValue
String
Hoiyor
The value of KYC field
11
KYCName
String
[Personal Details]
Yes
[Middle Name]
This KYC indicates the customers
middle name
12
KYCValue
String
The value of KYC field
13
KYCName
String
[Personal Details]
Yes
[Last Name]
This KYC indicates the customers last
name
14
KYCValue
String
Chen
The value of KYC field
Yes
Yes
Yes
Only the KYC fields of the customer name are fixed used here. That is, [Personal Detail][First Name], [Personal
Detail][Middle Name] and [Personal Detail][Last Name].
Sample of SOAP message:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:c2b="http://cps.huawei.com/cpsinterface/c2bpayment">
<soapenv:Header/>
PROJECT NAME: M-PESA G2
DOCUMENT NAME: DEVELOPERS GUIDE- PAYBILL
VALIDATION AND CONFIRMATION
VERSION: 0.3
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT
DATE: 3RD AUGUST 2015
<soapenv:Body>
<c2b:C2BPaymentValidationRequest>
<TransactionType>PayBill</TransactionType>
<TransID>1234560000007031</TransID>
<TransTime>20140227082020</TransTime>
<TransAmount>123.00</TransAmount>
<BusinessShortCode>12345</BusinessShortCode>
<BillRefNumber></BillRefNumber>
<InvoiceNumber></InvoiceNumber>
<MSISDN>254722703614</MSISDN>
<KYCInfo>
<KYCName>[Personal Details][First Name]</KYCName>
<KYCValue>Hoiyor</KYCValue>
</KYCInfo>
<KYCInfo>
<KYCName>[Personal Details][Middle Name]</KYCName>
<KYCValue>G</KYCValue>
</KYCInfo>
<KYCInfo>
<KYCName>[Personal Details][Last Name]</KYCName>
<KYCValue>Chen</KYCValue>
</KYCInfo>
</c2b:C2BPaymentValidationRequest>
</soapenv:Body>
</soapenv:Envelope>
Please refer to the CBPInterface_C2BPaymentValidationAndConfirmation.wsdl file in section 5 Annex for
detail.
4.1.2 PayBill Transaction Validation Result from Broker to MPesa
The detail of C2BPaymentValidationResult message from Broker to M-Pesa describes as following:
SN
Field
Name
Type
Example Option
Description
Value
al
ResultCode
string
ResultDesc
String
Service
processing Yes
successful
No
The result code of the authorization. 0 for success,
others are error code.
Error message when error occurs.
10
PROJECT NAME: M-PESA G2
DOCUMENT NAME: DEVELOPERS GUIDE- PAYBILL
VALIDATION AND CONFIRMATION
VERSION: 0.3
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT
DATE: 3RD AUGUST 2015
ThirdPartyTran
String
sID
The unique identifier of the payment transaction that
is generated by the third party
123456000
0088888
Yes
This field is reserved. The M-Pesa system can
accept the validation result with this field, but the
system will not process the field in current delivery.
The M-Pesa system regards the ResultCode 0 as success. Other result code are;
ResultCode
ResultDesc
C2B00011
Invalid MSISDN
C2B00012
Invalid Account number
C2B00013
Invalid Amount
C2B00014
Invalid KYC details
C2B00015
Invalid Shortcode
C2B00016
Other Error
Sample of SOAP message:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:c2b="http://cps.huawei.com/cpsinterface/c2bpayment">
<soapenv:Header/>
<soapenv:Body>
<c2b:C2BPaymentValidationResult>
<ResultCode>0</ResultCode>
<ResultDesc>Service processing successful</ResultDesc>
<ThirdPartyTransID>1234560000088888</ThirdPartyTransID>
</c2b:C2BPaymentValidationResult>
</soapenv:Body>
</soapenv:Envelope>
Please refer to the CBPInterface_C2BPaymentValidationAndConfirmation.wsdl file in section 7 Annex to see
the schema definition.
4.1.3 PayBill Transaction Confirmation Request from M-Pesa
to Broker
The detail of C2BPaymenConfirmationRequest message from M-Pesa to Broker describes as following:
11
PROJECT NAME: M-PESA G2
DOCUMENT NAME: DEVELOPERS GUIDE- PAYBILL
VALIDATION AND CONFIRMATION
VERSION: 0.3
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT
DATE: 3RD AUGUST 2015
SN Field Name
type
Example
Optional Description
value
TransType
String
BuyGoods
TransID
String
12345600000
07031
No
No
YYYYMMD
Dhhmmss
3
TransTime
String
20140227082
020
TransAmount
String
BusinessShortCod
String
e
12345
BillRefNumber
TX1001
String
The unique identifier of the payment
transaction that is generated by M-Pesa
system.
No
The date and time when customer
initiates a Buy Goods transaction.
No
The amount of the transaction. Two
decimals fixed point number. Fixed
Currency Type: KES e.g. 123.00 stands
for: 123.00 Ksh
No
The organization short code of the
Merchant in the M-Pesa system
Yes
This field is not applicable for Buy
123.00
4
The Transaction Type name of the Pay
Bill transaction.
12
PROJECT NAME: M-PESA G2
DOCUMENT NAME: DEVELOPERS GUIDE- PAYBILL
VALIDATION AND CONFIRMATION
VERSION: 0.3
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT
DATE: 3RD AUGUST 2015
Goods transactions. It will always be
blank.
Invoice Number as Entered by Identity
X334343
7
InvoiceNumber
String
Yes
12345.00
OrgAccountBalan
String
ce
No
Two decimals fixed point number. Fixed
Currency Type: KES e.g. 12345.00
stands for: 12345.00 Ksh
The unique identifier of the payment
transaction that is generated by the third
party
12345600000
88888
ThirdPartyTransI
String
D
This field is reserved. It will always be
blank in current delivery.
The Available Balance of the
organizations account for the Buy Goods
transaction (the Credit Party account of
the transaction).
Yes
This parameter only be present when
ThirdPartyTransID was returned from the
validation response message.
This field is reserved. It will always be
blank in current delivery.
10
MSISDN
String
25472270361
No
4
The customers MSISDN, which is with
country code prefix.
The customers KYC information, maybe
multiple KYC info.
KYCInfo
11
KYCName
String
[Personal
Details][First Yes
Name]
This KYC indicates the customers first
name
12
KYCValue
String
Hoiyor
Yes
The value of KYC field
Yes
This KYC indicates the customers
middle name
Yes
The value of KYC field
13
KYCName
String
[Personal
Details]
[Middle
Name]
14
KYCValue
String
15
KYCName
String
[Personal
Details][Last Yes
Name]
This KYC indicates the customers last
name
16
KYCValue
String
Chen
The value of KYC field
Yes
13
PROJECT NAME: M-PESA G2
DOCUMENT NAME: DEVELOPERS GUIDE- PAYBILL
VALIDATION AND CONFIRMATION
VERSION: 0.3
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT
DATE: 3RD AUGUST 2015
Sample of SOAP message:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:c2b="http://cps.huawei.com/cpsinterface/c2bpayment">
<soapenv:Header/>
<soapenv:Body>
<c2b:C2BPaymentConfirmationRequest>
<TransactionType>PayBill</TransactionType>
<TransID>1234560000007031</TransID>
<TransTime>20140227082020</TransTime>
<TransAmount>123.00</TransAmount>
<BusinessShortCode>12345</BusinessShortCode>
<BillRefNumber>TX1001</BillRefNumber>
<InvoiceNumber></InvoiceNumber>
<OrgAccountBalance>12345.00</OrgAccountBalance>
<ThirdPartyTransID></ThirdPartyTransID>
<MSISDN>254722703614</MSISDN>
<KYCInfo>
<KYCName>[Personal Details][First Name]</KYCName>
<KYCValue>Hoiyor</KYCValue>
</KYCInfo>
<KYCInfo>
<KYCName>[Personal Details][Middle Name]</KYCName>
<KYCValue>G</KYCValue>
</KYCInfo>
<KYCInfo>
<KYCName>[Personal Details][Last Name]</KYCName>
<KYCValue>Chen</KYCValue>
</KYCInfo>
</c2b:C2BPaymentConfirmationRequest>
</soapenv:Body>
</soapenv:Envelope>
Please refer to the CBPInterface_C2BPaymentValidationAndConfirmation.wsdl file in section 7 Annex to see
the schema definition.
4.1.4 PayBill Transaction Confirmation Result from Broker to
M-Pesa
The C2BPaymentConfirmationResult message from Broker to M-Pesa is free text, no functional usage of this free
text. It is only recorded in back-end log file in the M-Pesa system for traceability.
Sample of SOAP message:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:c2b="http://cps.huawei.com/cpsinterface/c2bpayment">
<soapenv:Header/>
<soapenv:Body>
<c2b:C2BPaymentConfirmationResult>C2B Payment Transaction 1234560000007031 result
received.</c2b:C2BPaymentConfirmationResult>
</soapenv:Body>
</soapenv:Envelope>
Please refer to the CBPInterface_C2BPaymentValidationAndConfirmation.wsdl file in section 5 Annex to see
the schema definition.
14
PROJECT NAME: M-PESA G2
DOCUMENT NAME: DEVELOPERS GUIDE- PAYBILL
VALIDATION AND CONFIRMATION
VERSION: 0.3
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT
DATE: 3RD AUGUST 2015
4.2 RegisterURL
4.2.1 RegisterURL interface specification
4.2.1.1
Interface Introduction
This service is for the third party system to register end-points on the broker where the validation and the
confirmation messages are sent.
The detail of RegisterURL message from the third party to Broker describes as following:
4.2.1.2
Data Type Definition
4.2.1.2.1
IdentifierType enumeration
List of IdentityType values.
Enumeration
Description
1
2
3
4
5
6
9
10
11
12
13
MSISDN
TillNumber
SPShortCode
OrganizationShortCode
IdentityID
O2CLink
SPOperatorCode
POSNumber
OrganizationOperatorUserName
OrganizationOperatorCode
VoucherCode
4.2.1.2.2
Element
name
Key
Value
ParameterType structure
Element
type
xsd:string
xsd:string
Optional
Description
No
No
It indicates a parameter name.
It indicates a parameter value.
4.2.1.2.3
Parameters structure
Element
name
Parameter
Element
type
ParameterTy
pe[1..unboun
ded]
Optional
Description
No
It is used to carry specific parameters for specific transaction or
business operation.
15
PROJECT NAME: M-PESA G2
DOCUMENT NAME: DEVELOPERS GUIDE- PAYBILL
VALIDATION AND CONFIRMATION
VERSION: 0.3
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT
DATE: 3RD AUGUST 2015
4.2.1.2.4
Element
name
ReferenceIte
m
4.2.1.2.5
ReferenceData structure
Element
type
ParameterTy
pe[1..unboun
ded]
Option
al
No
Description
It is used carry some reference data that MM need not analyze but
need to record it into transaction log..
Transaction structure
Element
name
CommandID
Element
type
xsd:string
Option
al
No
LanguageCod
e
OriginatorCo
nversationID
xsd:string
Yes
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.
ConversationI
D
xsd:string
Yes
Remark
Parameters
xsd:string
Parameters
Yes
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.
The remark information about this operation. Max length is 255
It is used to carry specific parameters for specific transaction or
business operation. This service will have one parameter type
ResponseType and the value can either be complete or cancel.
This is the action that will be taken in-case the 3rd party Validation
URL registered are not reachable.
ReferenceDat
a
ReferenceDat
a
No
Timestamp
xsd:string
No
4.2.1.2.6
Element
name
CallerType
Description
The unique identifier of transaction/business operation. Max length
is 64.eg
RegisterURL
It indicates language. Its reserved.
It is used carry some reference data that MM need not analyze but
need to record it into transaction log.
1. ValidationURL is the Key and the Value is the Validation
Service URL on the 3rd parties end.
2. ConfirmationURL is the Key and the Value is the
Confirmation Service URL on the 3rd parties end.
The timestamp generated by the third party.
Caller structure
Element
type
xsd:integer
Option
al
Yes
Description
Indicates the type of the caller:
2-APICaller
16
PROJECT NAME: M-PESA G2
DOCUMENT NAME: DEVELOPERS GUIDE- PAYBILL
VALIDATION AND CONFIRMATION
VERSION: 0.3
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT
DATE: 3RD AUGUST 2015
ThirdPartyID
xsd:string
Yes
Password
xsd:string
Yes
CheckSum
xsd:string
Yes
ResultURL
xsd:string
Yes
4.2.1.2.7
3-Other(Reserved). For this service use 2.
The unique identifier of a third party system defined in MM. It
indicates the third party which initiates the request. Max length is
20 This parameter is not used in this service. Leave it blank.
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. This parameter is not
used in this service. Leave it blank.
Currently it is unused. It is reserved for API security. This
parameter is not used in this service. Leave it blank.
It indicates the destination URL where Broker should send the
result message to. This parameter is not used in this service. Leave
it blank.
Initiator structure
Element
name
IdentifierType
Element
type
IdentifierTyp
e
Option
al
Yes
Identifier
xsd:string
Yes
SecurityCrede
ntial
xsd:string
Yes
ShortCode
xsd:string
Yes
4.2.1.2.8
Element
type
IdentifierTyp
e
Option
al
No
Identifier
ShortCode
xsd:string
xsd:string
Yes
No
Element name
It indicates the identifier type of the initiator. The value of this
parameter must be a valid identifier type supported by MM. For this
service use 11.
It indicates the identifier of the initiator. Its value must match the
inputted value of the parameter IdentifierType. This parameter is
not used in this service. Leave it blank.
It indicates the security credential of the initiator. Its value must
match the inputted value of the parameter IdentifierType. This
parameter is not used in this service. Leave it blank.
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. This parameter is not used in this service. Leave it
blank.
PrimaryParty structure
Element
name
IdentifierType
4.2.1.2.9
Description
Description
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.
Set as 1
It indicates a parameter value.
Short code of the Merchant Head office, store or C2B organisation
Identity structure
Element type
Optio
nal
Description
17
PROJECT NAME: M-PESA G2
DOCUMENT NAME: DEVELOPERS GUIDE- PAYBILL
VALIDATION AND CONFIRMATION
VERSION: 0.3
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT
DATE: 3RD AUGUST 2015
Caller
Initiator
Caller
Initiator
Yes
Yes
It indicates the third party which initiates the request
It indicates the identity who makes the request. An initiator
must be one of the following identity types:
SP operator
Organization operator(11)
NOTE
The value 11(Organization Operator) will be used for all
the services in this document.
PrimaryParty
PrimaryParty
No
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. The value 1 (Customer)
4.2.1.2.10 Request structure
Element
name
Transaction
Identity
KeyOwner
4.2.1.2.11
Element
type
Transaction
Identity
xsd:integer
Option
al
No
No
No
Description
It indicates a transaction.
This section is used to specify all identities involved in the request
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
For this service use 1.
Message Header: RequestSOAPHeader
Element name
Element type
Optional
SpId
xsd: string
No
Description
SP ID.
This is the Service Provider Identifier that is allocated by the
Broker to the 3rd party.
[Example] 000201
18
PROJECT NAME: M-PESA G2
DOCUMENT NAME: DEVELOPERS GUIDE- PAYBILL
VALIDATION AND CONFIRMATION
VERSION: 0.3
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT
DATE: 3RD AUGUST 2015
Element name
Element type
Optional
SpPassword
xsd: string
Yes
Description
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 SHA256 hash of the concatenation of the spId, password and the
timeStamp as illustrated below:
Given the following parameters
spId: 601399
password: spPassword
timestamp: 20130702212854
spPassword = BASE64(SHA-256(spId + Password + timeStamp))
e.g.
spPassword = BASE64(SHA256(601399spPassword20130702212854)
[Example]
e6434ef249df55c7a21a0b45758a39bb
ServiceId
xsd: string
Yes
Service ID.
This is the Service Identifier that is allocated by the Broker for
every service created.
[Example]
3500001000012
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]
20100731064245
4.2.1.2.12 Response structure
Element
name
ResponseCod
e
ResponseDes
c
ConversationI
D
Element
type
xsd:string
Option
al
No
Description
xsd:string
Yes
Its value is a description for the parameter ResultCode.
xsd:string
Yes
The unique identifier generated by M-Pesa for the request message.
It indicates whether MM accepts the request or not.
19
PROJECT NAME: M-PESA G2
DOCUMENT NAME: DEVELOPERS GUIDE- PAYBILL
VALIDATION AND CONFIRMATION
VERSION: 0.3
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT
DATE: 3RD AUGUST 2015
OriginatorCo
nversationID
ServiceStatus
4.2.1.3
xsd:string
Yes
xsd: integer
Yes
The unique identifier generated by the third party for the request
message.
It indicates the MM service status.
Instance
Request messages
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:req="http://apiv1.gen.mm.vodafone.com/mminterface/request">
<soapenv:Header>
<tns:RequestSOAPHeader xmlns:tns="http://www.huawei.com/schema/osg/common/v2_1">
<tns:spId>151515</tns:spId>
<tns:spPassword>ODExNERCMDlCNjVDRkYxQUFCNzE5MkE1OEQyMjJDMzk1RUFCNzgwMjk2ODE4Rjk1OTE2MEFGNDU1QkRCMDky
Mg==</tns:spPassword>
<tns:timeStamp>20140730093620</tns:timeStamp>
<tns:serviceId>151515001</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>RegisterURL</CommandID>
<OriginatorConversationID>Reg-266-1126</OriginatorConversationID>
<Parameters>
<Parameter>
<Key>ResponseType</Key>
<Value>Completed</Value>
</Parameter>
</Parameters>
<ReferenceData>
<ReferenceItem>
<Key>ValidationURL</Key>
<Value>http://10.66.49.201:8099/mock</Value>
</ReferenceItem>
<ReferenceItem>
<Key>ConfirmationURL</Key>
<Value>http://10.66.49.201:8099/mock</Value>
</ReferenceItem>
</ReferenceData>
</Transaction>
<Identity>
<Caller>
<CallerType>0</CallerType>
<ThirdPartyID/>
<Password/>
<CheckSum/>
20
PROJECT NAME: M-PESA G2
DOCUMENT NAME: DEVELOPERS GUIDE- PAYBILL
VALIDATION AND CONFIRMATION
VERSION: 0.3
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT
DATE: 3RD AUGUST 2015
<ResultURL/>
</Caller>
<Initiator>
<IdentifierType>1</IdentifierType>
<Identifier/>
<SecurityCredential/>
<ShortCode/>
</Initiator>
<PrimaryParty>
<IdentifierType>1</IdentifierType>
<Identifier/>
<ShortCode>898942</ShortCode>
</PrimaryParty>
</Identity>
<KeyOwner>1</KeyOwner>
</request>]]></req:RequestMsg>
</soapenv:Body>
</soapenv:Envelope>
Response messages
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:req="http://apiv1.gen.mm.vodafone.com/mminterface/request">
<soapenv:Header/>
<soapenv:Body>
<req:ResponseMsg><![CDATA[<?xml version="1.0" encoding="UTF-8"?><response xmlns="http://apiv1.gen.mm.vodafone.com/mminterface/response"><ResponseCode>00000000</ResponseCode><ResponseDesc>succ
ess</ResponseDesc><ConversationID></ConversationID><OriginatorConversationID></OriginatorConversatio
nID><ServiceStatus>0</ServiceStatus></response>]]></req:ResponseMsg>
</soapenv:Body>
</soapenv:Envelope>
21
PROJECT NAME: M-PESA G2
DOCUMENT NAME: DEVELOPERS GUIDE- PAYBILL
VALIDATION AND CONFIRMATION
VERSION: 0.3
COMPANY/DIVISION: PRODUCT AND SERVICE DEVELOPMENT
DATE: 3RD AUGUST 2015
Annex
The attached is the WSDL file adopted for Buy Goods external validation confirmation.
CBPInterface_C2BPaymentValidationAndConfirmation.wsdl
22
