Specification Document

Interswitch Virtual Topup Integration

Specification Document
Confidential
InterSwitch Limited
Interswitch Virtual Top-up Integration



























Document id
Document Title Virtual Topup Integration Specification
File Name and Path
Release date 3
rd
February, 2008
Number of pages
Author Olalekan Omotayo
Reviewers: Akintayo Akinfenwa
Change Control Date Comments Author

3
rd
February, 2008 Created Document Olalekan Omotayo

16
th
September, 2010 Migrated/Updated
Document
Williams Ilenikhena

12
th
February, 2013 Added Token,
ProductCode
Williams Ilenikhena

18
th
February, 2014 Added PIN to VendRequest Williams Ilenikhena


Comments

This document describes the message specification for VTUCare (Interswitch Virtual Top Up / Stock
Server) integration to a third party system (Virtual Topup Service Provider) for Virtual Top Up.


Specification Document
Confidential
InterSwitch Limited
Interswitch Virtual Top-up Integration

Table of Contents

1 INTRODUCTION ................................................................................................ 4
1.1 VIRTUAL TOPUP PROVIDER SERVICES ................................................... 5
1.1.1 VEND .....................................................................................................................5








































Specification Document
Confidential
InterSwitch Limited
Interswitch Virtual Top-up Integration
1 INTRODUCTION

VTUCare (Interswitchs Virtual Topup & Stock Server) receives Topup transaction requests from
channels downstream (ATM/POS/WEB/PCPOS/KIOSK/MOBILE), processes these requests and in the
case of Virtual Top Up forwards the message onwards to the Virtual Topup Service Provider for
fulfillment.

This document describes the defined standards for interaction between VTUCare and Virtual Topup
Service Providers that will exist upstream of VTUCare and participate in completing a transactions
lifecycle.

PROTOCOL
All Interaction will be via exchange of SOAP xml messages, where VTUCare as client will initiate an
HTTPS connection to a Virtual Topup Service Provider and communicate via sending a SOAP
message to the listening web service interface.

An SSL certificate will be provided to Interswitch by the Virtual Topup Service provider. This will be
used by the Virtual Topup Service provider to identify messages from VTUCare as a client.

Virtual Topup Service Provider may choose to implement Basic Http Authentication, this is however
not a compulsory requirement.


Specification Document
Confidential
InterSwitch Limited
Interswitch Virtual Top-up Integration
WEBSERVICE API

1.1 Virtual Topup Provider Services
1.1.1 VEND

This method requests that a subscriber be topped up and may also be used to poll
the Virtual Topup Provider service with dummy values.
Request Fields
Field M/O Length Format Description
DestAccount M 10 Alphanumeric Destination account the service number
to be topped up i.e., 2348052247125
Amount M n/a Numeric Integer value amount to Topup the
subscriber
Msg O n/a Alphanumeric Free form message that will be used as
part of the SMS notification
SequenceNo M n/a Numeric VTUCare generated reference for this
transaction
DealerNo M n/a Alphanumeric Dealer with Virtual Topup Provider whose
stock would be used to fulfil this order
Password M n/a Alphanumeric Password of Dealer with Virtual Topup
Provider whose stock will be used to fulfil
this order
ProductCode O n/a Alphanumeric A unique code that refers to the product
that is to be topped up
PIN O n/a Alphanumeric A value for the host to validate as
prerequisite for ValueToken vending
















Specification Document
Confidential
InterSwitch Limited
Interswitch Virtual Top-up Integration





Sample Request
<soapenv:Envelope xlmns:soapenv="http://schemas.xmlsoap.org./soap/envelope/"
xmlns:ret="http://vtu.glo.com" >
<!---Please maintain case for all request tags- ->
<soapenv:Header/>
<soapenv:Body>
< ret:Vend>
<DestAccount>2348052247125</DestAccount>
<Amount>500</Amount>
<Msg>From Shade</Msg>
<SequenceNo>1001</SequenceNo>
<DealerNo>INTERSWITCH</DealerNo>
<Password>INTERSWITCH</Password>
<ProductCode>628051043</ProductCode>
<PIN>098098080090809</PIN>
</ ret:Vend>
</soapenv:Body>
</soapenv:Envelope>


Response Fields
Field Description
StatusId The status of the Vend when executed on
the VTU Server e.g. 00 = Successful Vend.
The Client will have reference to the VTU
Statuss and their descriptions
StatusMessage The status message of the vend executed
on VTU
TxRefId The Unique Transaction Reference on the
Virtual Topup service providers platform
ValueToken Optional Field for returning Value to the
customer (Not Required for Virtual Top Up
integrations but necessary where the
customer depends on value response from
the organization upstream as Token i.e.,
Electricity meter token)
DealerNo Dealer with Virtual Topup Provider whose
stock would be used to fulfil this order
DestAccount The subscribers account e.g.
2348052247125
ResponseCode The Services status codes i.e. the status of
communication between the Client and

Specification Document
Confidential
InterSwitch Limited
Interswitch Virtual Top-up Integration
Service. 0 = Successful Meaning a request
was received, processed and some
response was given, further that the server
is up and available to process further
requests.

-1 = Communication / Processing failure
Meaning a request was received and some
error occurred while processing, further
that the server is unable to process further
requests.

This is the response that is looked out for
whenever the Virtual Topup Server is polled
ResponseMessage The Services status message corresponding
to the ResponseCode e.g.Success

Note: There may be exception scenarios (no response was received/processed for a
request) which will cause the request to be retried at intervals till a definite response is
received and processed; in such a case, the StatusId in the response from the host
should indicate that the transaction is a repeated transaction and the specific response
(value of StatusId/StatusMessage in the response) should depend on the
success/failure status of the initial transaction. Kindly, see Appendix 1.0 for a list of
standard responses. This list is in no way exhaustive.

Sample Response
<soapenv:Envelope xlmns:soapenv="http://schemas.xmlsoap.org./soap/envelope/"
xmlns:ret="http://vtu.glo.com">
<!---Please maintain case for all request tags- ->
<soapenv:Header/>
<soapenv:Body>
< ret:VendResponse>
<StatusId>00</StatusId>
<StatusMessage>Successful</StatusMessage>
<TxRefId>435435454</TxRefId>
<DealerNo>INTERSWITCH</DealerNo>
<DestAccount>2348052247125</DestAccount>
<Amount>500</Amount>
<ValueToken>03485454354534534</ValueToken>
<ResponseCode>0</ResponseCode>
<ResponseMessage>Success</ResponseMessage>
</ ret:VendResponse>
</soapenv:Body>
</soapenv:Envelope>







Specification Document
Confidential
InterSwitch Limited
Interswitch Virtual Top-up Integration




















APPENDIX

Specification Document
Confidential
InterSwitch Limited
Interswitch Virtual Top-up Integration
1.0 System Codes

Code Description
00 Successful
06 Error
11 Duplicate Transaction (Original transaction was received and was successful
i.e., it resulted in value to the customer)
13 Invalid Amount
17 Transaction Cancelled
40 Functionality not supported
55 Verification Failed
57 Transaction not permitted to subscriber
94 Duplicate Transaction (Original transaction was received and failed i.e., it did
not result in value to the customer)
96 Transaction processing error
98 Transaction limit exceeded
A9 Invalid Account (MSISDN)