uniPAYClient Integration Manual

uniPAY Client Interface

Version 2.0

This document contains commercial information and trade secrets, which are confidential
and proprietary in nature and are subject to protection under law. Access to the
information contained herein, howsoever acquired and of whatsoever nature, will not
entitle the receiver thereof to acquire any right thereto. The data subject to this restriction
are contained in all sheets of this document.

This document contains commercial or trade secrets of Innoviti Embedded Solution Pvt
Ltd. Disclosure of any such information or trade secrets shall not be made without the
prior written permission of Innoviti Embedded Solution Pvt Ltd.

Copyright © 2010 Innoviti Embedded Solutions Proprietary and Confidential

uniPAYClient Integration Manual

No part of this publication may be reproduced, stored in a retrieval system, or

transmitted, in any form or by any means, electronic, mechanical, photocopying,
recording, or otherwise, without the prior written permission of Innoviti Embedded
Solution Pvt Ltd.

The information in this document is subject to change without notice. The contents
mentioned in this document is furnished under license and may only be used or copied in
accordance with the terms of such license. All brand or product names are the trademarks
or registered trademarks of their respective holders.

Copyright © 2010 Innoviti Embedded Solutions Proprietary and Confidential

uniPAYClient Integration Manual

Document Revision History

Version Date Author Comment

1.0 26/02/2008 Prem Initial Version
1.1 26/02/2008 Prem Revisions based on internal reviews.
1.2 04/03/2008 Prem Revisions based on external reviews and discussion
1.3 05/03/2008 Navin Added server architecture and fault tolerance and
disaster recovery (integrated card payment
acceptance document)
1.4 09/03/2008 Navin Revision based on internal reviews
1.5 10/03/2008 Veda Revision based on internal reviews
1.6 15/06/2010 Prem Change made for VB calling method
1.7 15/07/2010 Nidhi Added Movie Tag
1.8 28/07/2010 Prem Add comments on mandatory field for Sale and
explained void transaction required field
1.9 19/10/2010 Gaurav Minor customization made in the interface to allow
new features.
2 15/11/2010 Kasi Changes made to allow Delphi integration.

Copyright © 2010 Innoviti Embedded Solutions Proprietary and Confidential

uniPAYClient Integration Manual

This page was intentionally left blank.

Copyright © 2010 Innoviti Embedded Solutions Proprietary and Confidential

uniPAYClient Integration Manual

Table of Contents

1 Overview.............................................................................................................................
1.1 Introduction.................................................................................................................
1.2 Integration Process and Billing POS feature..............................................................
2 Specification.......................................................................................................................
2.1 POS DLL Specification..............................................................................................
2.2 Sample Request and Response....................................................................................

Copyright © 2010 Innoviti Embedded Solutions Proprietary and Confidential

uniPAYClient Integration Manual

This page was intentionally left blank.

Copyright © 2010 Innoviti Embedded Solutions Proprietary and Confidential

uniPAYClient Integration Manual

1 Overview
1.1 Introduction
A critical aspect of operations is card payment acceptance systems at the point-of-sale.
Currently payment by cards (debit/credit) is carried out through stand-alone Electronic
Data Capture (EDC) machines that are not integrated with the billing systems at the
point-of-sale and connect to banks over legacy networks.

Innoviti Embedded Solutions is a provider of payment and transaction processing

technology and provides various hardware and software systems for improving
productivity and enhancing customer experience at the point-of-sale. It works with
leading banks in India and leading OEMs of various complementary technologies to put
together custom architectures for various payment and transaction processing
requirements.

This document captures the specification of the EFT application, Innoviti’s proposed
architecture, and interfaces for the same using various components.

1.2 Integration Process and Billing POS feature

For integration of EFT payments into a merchant's POS software, the checkout module in
POS software that handles customer payment can be modified to submit authorization
requests. Details on the request and response parameters are captured later in this
document.

Following is the transaction flow with integration for a sale transaction:

1. During checkout, merchant POS software (client) gets total amount which
customer has selected to be charged to credit card. This is the base amount for the
EFT transaction.
2. Using base amount, and other data (transaction token) POS software constructs
request parameter to be sent to dll.
3. POS software invokes innovEFT and passes request parameters.
4. Cashier swipes customer credit card in EDC to capture card track data.
5. POS software waits for response from innovEFT dll, response is received or
request times out (typical timeout value: 60 seconds).
6. When response is received, POS software parses response parameters, check
status code and response code and takes appropriate action.
7. Transaction complete: This case arises when uniPAY has completed a transaction
either successfully (ie. obtained approval) or otherwise.
Case 7a - Transaction approved. POS software notifies cashier of
transaction approval and approval code. POS software updates its local database using
information sent in response parameters. uniPAY also prints charge slip on the EDC to
obtain card holder's signature for verification.

Copyright © 2010 Innoviti Embedded Solutions Proprietary and Confidential

uniPAYClient Integration Manual

Case 7b - Transaction failed. Transaction failure can be due to a number of

reasons, for example, insufficient funds in card holder account, invalid expiry date,
connectivity error, transaction not allowed on card, etc. In this case, POS software
notifies cashier of error from response message sent in response parameters. POS
software can then prompt the cashier to re-try payment by repeating complete sequence
of steps as detailed above.

2 Specification
2.1 POS DLL Specification

The Innoviti DLL is a win32 DLL and is used as a bridging component between the
Innoviti’s uniPAY and the billing software (POS software).

A Win32 DLL is a library that can be made available to programs that run on a Microsoft
Windows(DLL supported OS) computer. As a normal library, it is made of functions and/
or other resources grouped in a file, the DLL abbreviation stands for Dynamic Link
Library. This means that, as opposed to a static library, a DLL allows the programmer to
decide on when and how other applications will be linked to this type of library. In fact,
applications created on different programming environments can use functions or
resources stored in one particular DLL.

About win32 DLL:-

The library contain information about functions included in the DLL and can locate it.
When an application needs to use a function contained in the DLL, it presents its request
to the import library. The import library checks the DLL for that function. If the function
exists, the client program can use it. If it doesn't, the library communicates this to the
application and the application presents an error.

Normally, the import library is created when building the DLL but we must provide a
mechanism for the compiler to initiate it. The POS DLL will be called through a method
(an API) by the Billing POS software during the billing process. It will be called at the
instance when card is selected as payment option.

During the billing process, if the tender process is selected as card (credit/debit), then the
POS software will pass the control to the DLL application with required data for
transaction. The DLL application will capture the card read event and will communicate
with the server using TCP/IP protocol exchanging data in ISO 8583 message format with
the server. The server in turn will forward the request to the bank as per bank

Copyright © 2010 Innoviti Embedded Solutions Proprietary and Confidential

uniPAYClient Integration Manual

configuration and return the bank response to the DLL application, which in turn will exit
with the required response being provided to the POS software.
Parsing of received packet will be done by POS software. This response can be used by
the POS software for carrying out printing (if required) and prompting errors (with reason
code) on the billing POS screen.

uniPAY Client API:

BSTR innovEFT (int REQUEST_TYPE, int REQUEST_MODE, char*

REQUEST_PARAMETERS)

Argument Description Type IN/OUT

REQUEST_TYPE Specifies mode of transaction request Integer IN
0 – SALE *
1- VOID *
3-REFUND
4-REDEEM
5-TOPUP
6-REWARD
7-BALANCEENQUIRY
8-Enrollment
9-Mobile Enrollment
11-Last 5 Recharge Transactions
12-Last 5 Redemption Transactions
13-Last 5 Transactions(including recharge
and redemption)
14-EOD Report
15-Group Join Request
16-Last EOD Report
17-UUN Extraction
18-charges+taxes
19-Late charges
20-Enrollment fees
21-Customer Search
22-renewal charges
23-Ask A Question
REQUEST_MODE Specifies type of Transaction request: Integer IN
0 – CREDIT/DEBIT *
1 - COUPON
2 - PREPAID
3 - LOYALTY
4 - SALE DEBIT (saving )
5- GIFT CARD
6- DISCOUNT CARD
7- STAFF CARD
8 - COG CARD
99 - OFFER CHECK
REQUEST_PARAMETERS Refer sample request String IN
RETURN STRING Refer sample response String OUT

* Supported actions

Copyright © 2010 Innoviti Embedded Solutions Proprietary and Confidential

uniPAYClient Integration Manual

2.2 Sample Request And Response

Sale Request Parameters

Transaction Input ID, Base Amount, Currency Code, Transaction Time,

Operator ID
ID000001,353505,INR,2009-09-19T09:50:55,0000

Transaction Input ID (max length 8, alphanumeric): Invoice number of

billing pos
Base Amount (max length 10+2, numeric): Amount( 353505 stands 3535.05
Rs)
Currency Code : INR
Transaction Time : Transaction Request Time (yyyy-MM-ddTHH:mm:ss)
Operator ID(max length 8, alphanumeric): logged in operator ID

Sample Sale Response Parameters

Transaction Input ID,Operator ID,Response Code,Response Message,

Approval Code, RRN,Base Amount, Card Number,Card Type, Card Holder
Name, Acquirer Bank, Transaction Time, optional details

Authorized Response:
ID000001,PLA123,00,Approved,787565,121212121212121,353505,4293XXXXXX9
89898,VISA,PREM KUMAR,AXIS BANK,2009-09-19T09:50:59, Master Card ^5
^0 ^500 ^834123 ^766543123465

Un-Successful Response:
ID000001,PLA123,03,DECLINED, , ,353505, 4293XXXXXX989898, , , ,2009-
09-19T09:50:59, MasterCard^ 5^ 0^ 500^ 834123^ 766543123465

Transaction Input ID: Invoice number of billing pos (Returned back

same value)
Operator ID: logged in operator ID
Response Code: Transaction Response code sent by bank
Response Message: Transaction Response Message sent by bank
Approval Code: Transaction Approval code sent by bank
RRN Number: Transaction RRN sent by bank
Base Amount: Amount( 353505 stands 3535.05 Rs)
Card Number: User Card Number
Card Type: Master/Visa/Amex etc

Copyright © 2010 Innoviti Embedded Solutions Proprietary and Confidential

uniPAYClient Integration Manual
Card Holder Name:
Acquirer Bank: Bank Name,Authorize the transaction
Transaction Time: Transaction Request Time (yyyy-MM-ddTHH:mm:ss)

Optional Parameter (*Not used): It is ^ separated having variables

Programtype^ discount^ amount^ approval Code^ RRN number,
Redeempoints^BalancePoints^optional1^optional2^optional3

MasterCard^5^500^834123^766543123465^0^0^0^0^0
Loyalty^0^1000^834123^766543123465^10^100^0^0^0

Program Type: Type of Program

Discount: Discount value depends on program
Amount: Discounted amount or loyalty amount value
Approval Code: approval code of Host (can be same as bank)
RRN Number: RRN of Host (can be same as bank)
Redeem Points: Loyalty Related
Balance Points: Loyalty Related
Optional 1: Future Use
Optional 2: Future Use
Optional 3: Future Use

Void Request Parameters

Transaction Input ID, Sale Transaction Invoice No, Currency Code,

Sale Transaction Time, Operator ID
ID000001,003404,INR,2009-09-19T09:50:55,0000

Transaction Input ID (max length 8, alphanumeric): Invoice number of

billing pos
Sale Transaction Invoice No. (length 6 fixed, numeric)
Currency Code : INR
Sale Transaction Time : Transaction Request Time (yyyy-MM-
ddTHH:mm:ss) as in the Sale Receipt
Operator ID(max length 8, alphanumeric): logged in operator ID

Sample Void Response Parameters

Transaction Input ID,Operator ID,Response Code,Response Message,

Approval Code, RRN,Base Amount, Card Number,Card Type, Card Holder
Name, Acquirer Bank, Transaction Time, optional details

Authorized Response:

Copyright © 2010 Innoviti Embedded Solutions Proprietary and Confidential

uniPAYClient Integration Manual

ID000001,PLA123,00,Approved,787565,121212121212121,353505,4293XXXXXX9
89898,VISA,PREM KUMAR,AXIS BANK,2009-09-19T09:50:59, Master Card ^5
^0 ^500 ^834123 ^766543123465

Un-Successful Response:
ID000001,PLA123,03,DECLINED, , ,353505, 4293XXXXXX989898, , , ,2009-
09-19T09:50:59, MasterCard^ 5^ 0^ 500^ 834123^ 766543123465

Transaction Input ID: Invoice number of billing pos (Returned back

same value)
Operator ID: logged in operator ID
Response Code: Transaction Response code sent by bank
Response Message: Transaction Response Message sent by bank
Approval Code: Transaction Approval code sent by bank
RRN Number: Transaction RRN sent by bank
Base Amount: Amount( 353505 stands 3535.05 Rs)
Card Number: User Card Number
Card Type: Master/Visa/Amex etc
Card Holder Name:
Acquirer Bank: Bank Name,Authorize the transaction
Transaction Time: Transaction Request Time (yyyy-MM-ddTHH:mm:ss)

Optional Parameter (*Not used): It is ^ separated having variables

Programtype^ discount^ amount^ approval Code^ RRN number,
Redeempoints^BalancePoints^optional1^optional2^optional3

MasterCard^5^500^834123^766543123465^0^0^0^0^0
Loyalty^0^1000^834123^766543123465^10^100^0^0^0

Program Type: Type of Program

Discount: Discount value depends on program
Amount: Discounted amount or loyalty amount value
Approval Code: approval code of Host (can be same as bank)
RRN Number: RRN of Host (can be same as bank)
Redeem Points: Loyalty Related
Balance Points: Loyalty Related
Optional 1: Future Use
Optional 2: Future Use
Optional 3: Future Use

END OF DOCUMENT

Copyright © 2010 Innoviti Embedded Solutions Proprietary and Confidential