C2B

 

Developer’s Guide


1.  Overview

When a customer initiates a Pay Bill service, the system will authorize the transaction (reserve funds) first 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.

1.1  Transaction Flow

C2B high level transaction flow diagram

C2B high level transaction flow diagram

1.2  PayBill Transaction Validation and Confirmation

A customer PayBill transaction can be initiated via STK or API channel. The transaction request will be sent to M-Pesa system for processing. After the M-Pesa system authorizes the transaction, an external transaction validation request will be sent to 3rd 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 being 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.

The confirmation message has no effect in the processing of the transaction.

 

Interface Specification

PayBill Transaction Validation and Confirmation

PayBill Transaction Validation Request from M-Pesa to Broker

The detail of C2BPaymentValidationRequest message from M-Pesa to Broker is describes as following:

SN Field Name Type Example value Optional Description
1 TransType String PayBill No The Transaction Type name of the BuyGoods transaction.
2 TransID String 1234560000007031 No The unique identifier of the payment transaction that is generated by M-Pesa system.
3 TransTime String YYYYMMDDhhmmss No The date and time when customer initiates a Buy Goods transaction.
20160227082020
4 TransAmount String 123 No The amount of the transaction. Two decimals fixed point number.  Fixed Currency Type: KES  e.g. 123.00  stands for: 123.00 Ksh
5 BusinessShortCode String 123456 No The organization short code of the Merchant in the M-Pesa system
6 BillRefNumber String TX1001 Yes This field is not applicable for Buy Goods transactions. It will always be blank.
7 InvoiceNumber String X334343 Yes Invoice Number as Entered by Identity
This field is reserved. It will always be blank in current delivery.
8 MSISDN String 254722703614 No The customer’s MSISDN, which is with country code prefix.
KYCInfo The customer’s KYC information, maybe multiple KYC info.
9 KYCName String [Personal Details][First Name] Yes This KYC indicates the customer’s first name
10 KYCValue String Hoiyor Yes The value of KYC field
11 KYCName String [Personal Details][Middle Name] Yes This KYC indicates the customer’s middle name
12 KYCValue String G Yes The value of KYC field
13 KYCName String [Personal Details][Last Name] Yes This KYC indicates the customer’s last name
14 KYCValue String Chen Yes The value of KYC field

Only the KYC fields of the customer name are fixed as 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/>

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

 

N/B:

Refer to CBPInterface_C2BPaymentValidationAndConfirmation.wsdl file to see the schema definition

 

PayBill Transaction Validation Result from Broker to M-Pesa

The detail of C2BPaymentValidationResult message from Broker to M-Pesa describes as following:

SN Field Name Type Example Value Optional Description
1 ResultCode string 0 No The result code of the authorization. 0 for success, others are error code.
2 ResultDesc String “Service processing successful” Yes Error message when error occurs.
3 ThirdPartyTransID String 1234560088809 Yes The unique identifier of the payment transaction that is generated by the third party
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 returns the ResultCode 0 as success. Other result codes can be freely used for the Broker to indicate error types. Please see also in the ‘Exceptions’ section for the processing in this case.

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>

N/B

Refer to CBPInterface_C2BPaymentValidationAndConfirmation.wsdl file to see the schema definition

 

PayBill Transaction Confirmation Request from M-Pesa to Broker

The detail of C2BPaymenConfirmationRequest message from M-Pesa to Broker describes as following:

SN Field Name type Example value Optional Description
1 TransType String BuyGoods No The Transaction Type name of the Pay Bill transaction.
2 TransID String 1234560000007031 No The unique identifier of the payment transaction that is generated by M-Pesa system.
3 TransTime String YYYYMMDDhhmmss No The date and time when customer initiates a Buy Goods transaction.
20160227082020
4 TransAmount String 123 No The amount of the transaction. Two decimals fixed point number.  Fixed Currency Type: KES  e.g. 123.00  stands for: 123.00 Ksh
5 BusinessShortCode String 12345 No The organization short code of the Merchant in the M-Pesa system
6 BillRefNumber String TX1001 Yes This field is not applicable for Buy Goods transactions. It will always be blank.
7 InvoiceNumber String X334343 Yes Invoice Number as Entered by Identity
This field is reserved. It will always be blank in current delivery.
8 OrgAccountBalance String 12345 No The Available Balance of the organization’s account for the Buy Goods transaction (the Credit Party account of the transaction).
Two decimals fixed point number.  Fixed Currency Type: KES  e.g. 12345.00  stands for: 12345.00 Ksh
9 ThirdPartyTransID String 123456000008889 Yes The unique identifier of the payment transaction that is generated by the third party
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 254722703614 No The customer’s MSISDN, which is with country code prefix.
KYCInfo The customer’s KYC information, maybe multiple KYC info.
11 KYCName String [Personal Details][First Name] Yes This KYC indicates the customer’s first name
12 KYCValue String Hoiyor Yes The value of KYC field
13 KYCName String [Personal Details][Middle Name] Yes This KYC indicates the customer’s middle name
14 KYCValue String G Yes The value of KYC field
15 KYCName String [Personal Details][Last Name] Yes This KYC indicates the customer’s last name
16 KYCValue String Chen Yes The value of KYC field

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>

N/B

Refer to CBPInterface_C2BPaymentValidationAndConfirmation.wsdl file to see the schema definition

 

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>

N/B

Refer to CBPInterface_C2BPaymentValidationAndConfirmation.wsdl file to see the schema definition.

 

RegisterURL

RegisterURL interface specification

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 details of RegisterURL message from the third party to Broker are described as following:

Data Type Definition

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
RegisterURL
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_Org_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. 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.
ReferenceData ReferenceData No 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.
Timestamp xsd:string No The timestamp generated by the third party.
Caller structure
Element name Element type Optional Description
CallerType xsd:integer Yes Indicates the type of the caller:
2-APICaller
3-Other(Reserved). For this service use 2.
ThirdPartyID xsd:string Yes 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.
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. This parameter is not used in this service. Leave it blank.
CheckSum xsd:string Yes Currently it is unused. It is reserved for API security. This parameter is not used in this service. Leave it blank.
ResultURL xsd:string Yes 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 Element type Optional Description
IdentifierType IdentifierType Yes 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.
Identifier xsd:string Yes 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.
SecurityCredential xsd:string Yes 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.
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. This parameter is not used in this service. Leave it blank.
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.
Set as 1
Identifier xsd:string Yes It indicates a parameter value.
ShortCode xsd:string No Short code of the Merchant Head office, store or C2B organisation
Identity structure
Element name Element type Optional Description
Caller Caller Yes It indicates the third party which initiates the request
Initiator Initiator Yes 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) 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)
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
For this service use 1.
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
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.
 Sample RegisterURL API Call

<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>107031</tns:spId>
<tns:spPassword>NjBjMzJmYTY0OWFjNDBmNjExOWM4YjVmMzg4NjFkNDc0NoApLNWVlZTI4MDYyNDM1MGRRmNmNlMTAyNWJiNA==</tns:spPassword>
<tns:timeStamp>yyyyMMddhhmmss</tns:timeStamp>
<tns:serviceId>107031000</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>111111_ORG880802l3</OriginatorConversationID>
<Parameters>
<Parameter>
<Key>ResponseType</Key>
<Value>Completed</Value>
</Parameter>
</Parameters>
<ReferenceData>
<ReferenceItem>
<Key>ValidationURL</Key>
<Value>http://11.11.11.11/services/PaymentsService/validate</Value>
</ReferenceItem>
<ReferenceItem>
<Key>ConfirmationURL</Key>
<Value>http://11.11.11.11/services/PaymentsService/confirmation</Value>
</ReferenceItem>
</ReferenceData>
</Transaction>
<Identity>
<Caller>
<CallerType>2</CallerType>
<ThirdPartyID/>
<Password/>
<CheckSum/>
<ResultURL/>
</Caller>
<Initiator>
<IdentifierType>11</IdentifierType>
<Identifier/>
<SecurityCredential/>
<ShortCode/>
</Initiator>
<PrimaryParty>
<IdentifierType>1</IdentifierType>
<Identifier/>
<ShortCode>111111</ShortCode>
</PrimaryParty>
</Identity>
<KeyOwner>1</KeyOwner>
</request>]]></req:RequestMsg>
</soapenv:Body>
</soapenv:Envelope>

Sample RegisterURL Response To 3rd Party

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