INSIGHT PAYMENT GATEWAY - SPECIFICATION DOCUMENT

B2C
Billing & IT – Mobile Money and VAS

INSIGHT PAYMENT GATEWAY -

SPECIFICATION DOCUMENT

B2C

Version 1.3

10 August 2018

Document Owner: Belewete, Christian, Vodacom DRC

Vodacom Proprietary and Confidential. Rev4

Copyright © 2018. Vodacom Congo S.A
Page 1 of 18
 INSIGHT PAYMENT GATEWAY - SPECIFICATION DOCUMENT
B2C
Billing & IT – Mobile Money and VAS

Version History

Version Date Changed By Change summary

1.0. 17-Jul-18 Christian Belewete Initial draft

1.1 20-Jul-18 Christian Belewete Adding Service flow

1.2 24-Jul-18 Christian Belewete Adding Login request parameters
1.3 10-Aug-18 Christian Belewete Adding test details

Vodacom Proprietary and Confidential. Rev4

Copyright © 2018. Vodacom Congo S.A
Page 2 of 18
 INSIGHT PAYMENT GATEWAY - SPECIFICATION DOCUMENT
B2C
Billing & IT – Mobile Money and VAS

Contents
Version History.............................................................................................................................................. 2
1 Introduction .......................................................................................................................................... 4
1.1 Prerequisites ................................................................................................................................. 4
2 Service flow ........................................................................................................................................... 5
3 Test details ............................................................................................................................................ 6
4 API Calls Parameters ............................................................................................................................. 7
4.1 Login .............................................................................................................................................. 7
4.1.1 Request Parameters .............................................................................................................. 7
4.1.2 Response Parameters ........................................................................................................... 7
4.2 B2C ................................................................................................................................................ 8
4.2.1 Request Parameters .............................................................................................................. 8
4.2.2 Response Parameters ........................................................................................................... 9
5 API Calls Samples ................................................................................................................................ 10
5.1 Login ............................................................................................................................................ 10
5.1.1 Request ............................................................................................................................... 10
5.1.2 Response ............................................................................................................................. 10
5.2 B2C .............................................................................................................................................. 12
5.2.1 Request ............................................................................................................................... 12
5.2.2 Response ............................................................................................................................. 14
5.2.3 Callback Result .................................................................................................................... 16

Vodacom Proprietary and Confidential. Rev4

Copyright © 2018. Vodacom Congo S.A
Page 3 of 18
 INSIGHT PAYMENT GATEWAY - SPECIFICATION DOCUMENT
B2C
Billing & IT – Mobile Money and VAS

1 Introduction

The iNSight Payment Gateway sits in front of G2 which manages a customer’s wallet. This wallet, in the
case of mobile network operators, the “Mobile Money Platform” is physically separated from the
payment gateway (sometimes also referred to as a “Broker” or an “Orchestration Layer”) providing the
benefit of a simplified interface and abstraction of both function and security.

1.1 Prerequisites
In order to issue any query against the iNSight Payment Gateway, a valid session token is required (as
described in the referenced document “TxS_InterfaceBase”).

The following data must be supplied by the owner of the system in order to be able to communicate
with iNSight Payment Gateway.

- Service Provider Code

- URL for the web service

- Username

- Password

Requests must be posted to iNSight Payment Gateway via the SOAP web service. The web service will be
accessible via HTTPs only. The operation will be either Synchronous or Asynchronous depending on
what is exposed by the Mobile Money platform (a platform that employs a Synchronous approach could
be exposed via iNSight Payment Gateway as either Synchronous or Asynchronous.

Vodacom Proprietary and Confidential. Rev4

Copyright © 2018. Vodacom Congo S.A
Page 4 of 18
 INSIGHT PAYMENT GATEWAY - SPECIFICATION DOCUMENT
B2C
Billing & IT – Mobile Money and VAS

2 Service flow

1. The third party initiates the process by sending the Login Request

2. On a successful login, M-Pesa respond with a SessionID

3. Third Party system sends B2C Request, using SessionID received in step 2 as token. M-Pesa will send a
acknowledge response.

4. After processing the request, M-Pesa will forward the final result of to the Third Party Callback Url
sent on the B2C Request.

5. The Third Party has to send a response with the required format.

Vodacom Proprietary and Confidential. Rev4

Copyright © 2018. Vodacom Congo S.A
Page 5 of 18
 INSIGHT PAYMENT GATEWAY - SPECIFICATION DOCUMENT
B2C
Billing & IT – Mobile Money and VAS

3 Test details

Login
URL Login https://uatipg.m-pesa.vodacom.cd:8091/insight/SOAPIn
URL B2C https://uatipg.m-pesa.vodacom.cd:8094/iPG/B2C
Internal IP 10.90.104.50
Public IP 41.78.195.169
Event ID Login 2500
Event ID B2C 12001
CommandID InitTrans_one4allb2c
ShortCode/ServiceProviderCode 15058

Vodacom Proprietary and Confidential. Rev4

Copyright © 2018. Vodacom Congo S.A
Page 6 of 18
 INSIGHT PAYMENT GATEWAY - SPECIFICATION DOCUMENT
B2C
Billing & IT – Mobile Money and VAS

4 API Calls Parameters

4.1 Login
4.1.1 Request Parameters

Name Notes Type

Header
EventID ID of the event to be actioned Integer Required
on Transaction Switch. This is a
fixed value for Login of 2500
Request Data Items
Username Username to validate String Required
Password Password of the user to String Required
validate

4.1.2 Response Parameters

Name Notes Type Sample Values

Event Info
code iNSight process status Integer 3, 4
code
description Description of the iNSight String Processed, Error
process status code
detail Additional information String Processed,
about iNSight process Authentication
Failed
Request Data Items
Username Username that was String Same as value sent
evaluated in request
Password Password of the user that String Same as value sent
was evaluated in request

Response Data Items

SessionID In the case of a valid login, String da6be0443e53411ebd90
the session id to be used as ad0aec7a97ab
the Token ID for future
event calls

Vodacom Proprietary and Confidential. Rev4

Copyright © 2018. Vodacom Congo S.A
Page 7 of 18
 INSIGHT PAYMENT GATEWAY - SPECIFICATION DOCUMENT
B2C
Billing & IT – Mobile Money and VAS

4.2 B2C
4.2.1 Request Parameters

Name Notes Type

Header
Token Token received from a Login request String Required
EventID ID of the event to be actioned on Integer Required
Transaction Switch.
Request Data Items
ServiceProviderName Name of the service provider. For String Required
example: FINCA
CustomerMSISDN MSISDN of the customer String Required
Currency Currency Code for the transaction. String Required
For example: CDF or USD
Amount Amount of the said currency to String Required
transfer from the Third-Party to the
customer
TransactionDateTime Date of the transaction. Format Date Optional
YYYYMMDD HH24MiSS.
Shortcode Shortcode of the Third-Party in M- String Required
Pesa where funds will move from.
CustomerAccountNumber Customer’s Third-Party account String Optional
number.
Language Customer’s language choice. String Required
ThirdPartyReference The Third-Party’s Transaction ID. String Required
CallBackChannel The channel used to send the results String Required
of the transaction to the third party.
1. Synchronous (default and only
available if Mobile Money system is
synchronus)
2. Async HTTP Post
3. Async SMS

4.Async eMail
CallBackDestination Dependant on CallBackChannel String Required
Should be populated with relevant
URL, MSISDN (format example
243821111111) or email address
CommandID M-Pesa CommandID. M-Pesa team String Required
to provide.
InitiatorIdentifier Third-Party’s Identifier. M-Pesa String Optional
team to provide.
SecurityCredential Third-Party’s Password. M-Pesa String Optional
team to provide.

Vodacom Proprietary and Confidential. Rev4

Copyright © 2018. Vodacom Congo S.A
Page 8 of 18
 INSIGHT PAYMENT GATEWAY - SPECIFICATION DOCUMENT
B2C
Billing & IT – Mobile Money and VAS

4.2.2 Response Parameters

Name Notes Type Sample Values

Event Info
Code iNSight process status Integer 3, 4
code
Description Description of the String Processed, Error
iNSight process status
code
Detail Additional information String Authentication Failed,
about iNSight process Session Expired
TransactionID Transaction ID from the payment String
gateway
Request Data Items
ServiceProviderName String Same as value sent in request
CustomerMSISDN String Same as value sent in request
Currency String Same as value sent in request
Amount String Same as value sent in request
TransactionDateTime Date Same as value sent in request
Shortcode String Same as value sent in request
CustomerAccountNumber String Same as value sent in request
Language String Same as value sent in request
ThirdPartyReference String Same as value sent in request
ServiceProviderName String Same as value sent in request
CallBackChannel String Same as value sent in request
CallBackDestination String Same as value sent in request
CommandID String Same as value sent in request
InitiatorIdentifier String Same as value sent in request
SecurityCredential String Same as value sent in request

Response Data Items

Insight_txid The unique String 12sdxq3634dadsas242
transaction ID
from iPG
ResponseCode Code indicating String 0, -1, -2
the result of the
transaction.
0 –Received
request
successfully.
-1 – Transaction
will not be
processed. Try
again later.

Vodacom Proprietary and Confidential. Rev4

Copyright © 2018. Vodacom Congo S.A
Page 9 of 18
 INSIGHT PAYMENT GATEWAY - SPECIFICATION DOCUMENT
B2C
Billing & IT – Mobile Money and VAS

5 API Calls Samples

5.1 Login
5.1.1 Request

<?xml version="1.0" encoding="UTF-8"?>

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soap="http://www.4cgroup.co.za/soapauth"
xmlns:gen="http://www.4cgroup.co.za/genericsoap">
<soapenv:Header>
<soap:EventID>2500</soap:EventID>
</soapenv:Header>
<soapenv:Body>
<gen:getGenericResult>
<Request>
<dataItem>
<name>Username</name>
<type>String</type>
<value>{{ USERNAME }}</value>
</dataItem>
<dataItem>
<name>Password</name>
<type>String</type>
<value>{{ PASSWORD }}</value>
</dataItem>
</Request>
</gen:getGenericResult>
</soapenv:Body>
</soapenv:Envelope>

5.1.2 Response

<?xml version='1.0' encoding='UTF-8'?>

<S:Envelope
xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<S:Header>
<ns3:eventid
xmlns:ns2="http://www.4cgroup.co.za/genericsoap"
xmlns:ns3="http://www.4cgroup.co.za/soapauth">2500
</ns3:eventid>
</S:Header>
<S:Body>
Vodacom Proprietary and Confidential. Rev4
Copyright © 2018. Vodacom Congo S.A
Page 10 of 18
 INSIGHT PAYMENT GATEWAY - SPECIFICATION DOCUMENT
B2C
Billing & IT – Mobile Money and VAS

<ns2:getGenericResultResponse
xmlns:ns2="http://www.4cgroup.co.za/genericsoap"
xmlns:ns3="http://www.4cgroup.co.za/soapauth">
<SOAPAPIResult>
<eventInfo>
<code>3</code>
<description>Processed</description>
<detail>Processed</detail>
<transactionID>0c49ec4bbebe44b082aa24e5f548b514</transactionID>
</eventInfo>
<request>
<dataItem>
<name>Username</name>
<type>String</type>
<value>thirdpartyc2bw</value>
</dataItem>
<dataItem>
<name>Password</name>
<type>String</type>
<value>thirdpartyc2bw</value>
</dataItem>
</request>
<response>
<dataItem>
<name>SessionID</name>
<type>String</type>
<value>dbcb63a40afd4191a990d66ed9cb62f7</value>
</dataItem>
</response>
</SOAPAPIResult>
</ns2:getGenericResultResponse>
</S:Body>
</S:Envelope>

Vodacom Proprietary and Confidential. Rev4

Copyright © 2018. Vodacom Congo S.A
Page 11 of 18
 INSIGHT PAYMENT GATEWAY - SPECIFICATION DOCUMENT
B2C
Billing & IT – Mobile Money and VAS

5.2 B2C
5.2.1 Request

<?xml version="1.0" encoding="UTF-8"?>

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header>
<soap:EventID
xmlns:soap="http://www.4cgroup.co.za/soapauth">12001</soap:EventID>
<soap:Token
xmlns:soap="http://www.4cgroup.co.za/soapauth">{{ TOKEN }}</soap:Token>
</soapenv:Header>
<soapenv:Body>
<gen:getGenericResult
xmlns:gen="http://www.4cgroup.co.za/genericsoap">
<Request>
<dataItem>
<name>ServiceProviderName</name>
<type>String</type>
<value>ONE4ALL</value>
</dataItem>
<dataItem>
<name>CustomerMSISDN</name>
<type>String</type>
<value>{{ MSISDN }}</value>
</dataItem>
<dataItem>
<name>Currency</name>
<type>String</type>
<value>USD</value>
</dataItem>
<dataItem>
<name>Amount</name>
<type>String</type>
<value>1</value>
</dataItem>
<dataItem>
<name>TransactionDateTime</name>
<type>Date</type>
<value>20180601123700</value>
</dataItem>
<dataItem>
<name>Shortcode</name>
<type>String</type>
<value>15058</value>
</dataItem>
<dataItem>
<name>Language</name>

Vodacom Proprietary and Confidential. Rev4

Copyright © 2018. Vodacom Congo S.A
Page 12 of 18
 INSIGHT PAYMENT GATEWAY - SPECIFICATION DOCUMENT
B2C
Billing & IT – Mobile Money and VAS

<type>String</type>
<value>EN</value>
</dataItem>
<dataItem>
<name>ThirdPartyReference</name>
<type>String</type>
<value>Christian-Test1</value>
</dataItem>
<dataItem>
<name>CallBackChannel</name>
<type>String</type>
<value>2</value>
</dataItem>
<dataItem>
<name>CallBackDestination</name>
<type>String</type>
<value>https://mmdrc.myone4all.com/xmlapi/sevice/callbackurl</value>
</dataItem>
<dataItem>
<name>CommandID</name>
<type>String</type>
<value>InitTrans_one4allb2c</value>
</dataItem>

</Request>
</gen:getGenericResult>
</soapenv:Body>
</soapenv:Envelope>

Vodacom Proprietary and Confidential. Rev4

Copyright © 2018. Vodacom Congo S.A
Page 13 of 18
 INSIGHT PAYMENT GATEWAY - SPECIFICATION DOCUMENT
B2C
Billing & IT – Mobile Money and VAS

5.2.2 Response

<?xml version='1.0' encoding='UTF-8'?>

<S:Envelope
xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<S:Header>
<ns3:eventid
xmlns:ns2="http://www.4cgroup.co.za/genericsoap"
xmlns:ns3="http://www.4cgroup.co.za/soapauth">12001
</ns3:eventid>
</S:Header>
<S:Body>
<ns2:getGenericResultResponse
xmlns:ns2="http://www.4cgroup.co.za/genericsoap"
xmlns:ns3="http://www.4cgroup.co.za/soapauth">
<SOAPAPIResult>
<eventInfo>
<code>3</code>
<description>Processed</description>
<detail>Processed</detail>
<transactionID>74b2f36481524d1e9bf907edbc86291d</transactionID>
</eventInfo>
<request>
<dataItem>
<name>ServiceProviderName</name>
<type>String</type>
<value>ONE4ALL</value>
</dataItem>
<dataItem>
<name>CustomerMSISDN</name>
<type>String</type>
<value>243811835361</value>
</dataItem>
<dataItem>
<name>Currency</name>
<type>String</type>
<value>USD</value>
</dataItem>
<dataItem>
<name>Amount</name>
<type>String</type>
<value>1</value>
</dataItem>
<dataItem>
<name>TransactionDateTime</name>
<type>Date</type>
<value>20180601123700</value>
</dataItem>
Vodacom Proprietary and Confidential. Rev4
Copyright © 2018. Vodacom Congo S.A
Page 14 of 18
 INSIGHT PAYMENT GATEWAY - SPECIFICATION DOCUMENT
B2C
Billing & IT – Mobile Money and VAS

<dataItem>
<name>Shortcode</name>
<type>String</type>
<value>15058</value>
</dataItem>
<dataItem>
<name>Language</name>
<type>String</type>
<value>EN</value>
</dataItem>
<dataItem>
<name>ThirdPartyReference</name>
<type>String</type>
<value>Christian-Test1</value>
</dataItem>
<dataItem>
<name>CallBackChannel</name>
<type>String</type>
<value>2</value>
</dataItem>
<dataItem>
<name>CallBackDestination</name>
<type>String</type>
<value>https://callbackurl</value>
</dataItem>
<dataItem>
<name>CommandID</name>
<type>String</type>
<value>InitTrans_one4allb2c</value>
</dataItem>
</request>
<response>
<dataItem>
<name>Insight_txid</name>
<type>String</type>
<value>lurzsmmaxquh9l1svold6e3hx7x7jp9t</value>
</dataItem>
<dataItem>
<name>ResponseCode</name>
<type>String</type>
<value>0</value>
</dataItem>
</response>
</SOAPAPIResult>
</ns2:getGenericResultResponse>
</S:Body>
</S:Envelope>

Vodacom Proprietary and Confidential. Rev4

Copyright © 2018. Vodacom Congo S.A
Page 15 of 18
 INSIGHT PAYMENT GATEWAY - SPECIFICATION DOCUMENT
B2C
Billing & IT – Mobile Money and VAS

5.2.3 Callback Result

To receive the result of an Asynchronous event call via an HTTP post, the CallBackChannel must be set to
“2”. The CallBackDestination should also carry the URL that should be posted to from iNSight (it is
important that iNSight can access this URL). The envelope posted will be a SOAP envelope. iNSight must
be able to post without needing to authenticate or needing to perform any preliminary steps. The Third-
Party must reply with the specified Response packet.

Request sent to the third party

URL: http://xxx.xxx.xxx.xxx:aaa/insight/SOAPIn POST /insight/SOAPIn HTTP/1.1 Host: xxxxxxxx Content-type:text/xml;

charset=utf-8
<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soap="http://www.4cgroup.co.za/soapauth"
xmlns:gen="http://www.4cgroup.co.za/genericsoap">
<soapenv:Header>
<soap:EventID>1</soap:EventID>
</soapenv:Header>
<soapenv:Body>
<gen:getGenericResult>
<Request>
<dataItem>
<name>ResultType</name>
<value>0</value>
<type>String</type>
</dataItem>
<dataItem>
<name>ResultCode</name>
<value>0</value>
<type>String</type>
</dataItem>
<dataItem>
<name>ResultDesc</name>
<value> Process service request successfully.</value>
<type>String</type>
</dataItem>
<dataItem>
<name>OriginatorConversationId</name>
<value>fbb550d9eb924e8e99ac1aa7ff8c05d0</value>
<type>String</type>
</dataItem>
<dataItem>
<name>ConversationId</name>
<value>0c9766a5-1c9e-4ffa-b815-3b447dde5cb1</value>

Vodacom Proprietary and Confidential. Rev4

Copyright © 2018. Vodacom Congo S.A
Page 16 of 18
 INSIGHT PAYMENT GATEWAY - SPECIFICATION DOCUMENT
B2C
Billing & IT – Mobile Money and VAS

<type>String</type>
</dataItem>
<dataItem>
<name>TransactionID</name>
<value>X-BS281</value>
<type>String</type>
</dataItem>
<dataItem>
<name>Amount</name>
<value>200</value>
<type>String</type>
</dataItem>
<dataItem>
<name>TransactionTime</name>
<value>20170301T22:59:01</value>
<type>String</type>
</dataItem>
<dataItem>
<name>ThirdPartyReference</name>
<value>123456-Test</value>
<type>String</type>
</dataItem>
<dataItem>
<name>InsightReference</name>
<value>12sdxq3634dadsas242</value>
<type>String</type>
</dataItem>
</Request>
</gen:getGenericResult>
</soapenv:Body>
</soapenv:Envelope>

Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<response>
<dataItem>
<name>ResponseCode</name>
<type>String</type>
<value>200</value>
</dataItem>
<dataItem>
<name>RESULT_CODE</name>
<type>String</type>
<value>Received</value>
</dataItem>
</response>

Vodacom Proprietary and Confidential. Rev4

Copyright © 2018. Vodacom Congo S.A
Page 17 of 18
 INSIGHT PAYMENT GATEWAY - SPECIFICATION DOCUMENT
B2C
Billing & IT – Mobile Money and VAS

Vodacom Proprietary and Confidential. Rev4

Copyright © 2018. Vodacom Congo S.A
Page 18 of 18