iPAYServlet documentation and description (version 3.4 August 15th 2000)

More info is on http://www.neweconomyservices.com

And http://www.ok.ee/~andri/java/iPAY/index.html




Table of contents

1.   Using iPAYServlet as e-commerce server†††††††††††††††††††††††††††††††††††††††††††††††††††††††† 1

2.   Using iPAYServlet as an POS replacement (WEB-POS)††††††††††††††††††††††††††            1

3.   iPAYServlet functions and features††††††††††††††††††††††††††††††††††††††††††††††††††††††††††††††††† 2

4.   iPAYServlet technical specification†††††††††††††††††††††††††††††††††††††††††††††††††††††††††††††††††† 2





1. Using iPAYServlet as e-commerce server


iPAYSservlet can be used as e-commerce server for e-shops and other e-services where credit card payments need to be processed. iPAYServlet works on principle that cardholder will enter his card number and other card related data (expiration date). Then the authorization request in (ISO8583 format) with information provided will performed through acquirer system in local bank or VISA or MasterCard network. In case of positive authorization result the system saves a new transaction record into database and user will be informed about successful transaction. The iPAYServlet has currently 3 different user/merchant feedback methods:

1.   iPAYServlet will generate a feedback page for user and will send a http request to merchant system.

2.   iPAYServlet will generate a feedback page with link whcih returns to merchant site with the feedback information.

3.   iPAYServlet will generate automatic redirection page to send authorization feedback to merchant and allows merchant to generate page related to this feedback.



2. Using iPAYServlet as an POS replacement (WEB-POS)


iPAYServlet can be used as replacement of POS device everywhere where is present a PC or network terminal which has internet connection, magnet card reader and web browser. It is recommended to have a permanent network connection or ISDN for quick operation. Only if you have very few transaction you may use dial-up. With modem dial-up the whole process can take up to 1..3 minutes depending on your connection establishing speed. In case of permanent connection normal authorization processing will delay from 5 to 15 seconds. The most convenient way to use WEB-POS is do it through service provider (acquirer or processor) who has installed iPAYServlet and related databases.

The first WEB-POS service provider in Estonia is Pankade Kaardikeskus (Card Centre of Banks https://pos.estcard.ee). To use WEB-POS at service provider you need to make an agreement and then you may go to service provider WEB-POS website and enter your username and password to login. After login you can start easily to make authorizations, reversals and check status and summary reports of your transactions.

iPAYServlet can also used in personal system but in this case you need to install a servlet engine and an SQL database (PostgreSQL, MYSQL or other jdbc enabled SQL server).You will also need to have a connection to acquirer/processor system via TCP/IP network.


In both cases you will save lot of money so you donít need to buy expensive and dummy POS devices and you have more features and better quality of service.


3. iPAYServlet functions and features


iPAYServlet has following features:

- authorization and reversal requests using http/https protocol over internet or LAN

- forward authorization request to acquirer network through TCP/IP network

- watch reports of your transactions in detailed or summary form

- manage transactions to be collected for batch processing

- fraud filter to protect system from card number generators and similar activities

- user can change password

- ISO8583 version 1997 and 1993 based authorization message protocols

- transaction file transfer to acquirer system

- By now iPAYServlet is tested and used with following technologies:

java servlet development kit, Apache web server with jserv and with following SQL servers: PostgreSQL, MySQL.



4. iPAYServlet technical Specification


iPAYServletís input/output parameters:


iPAYServletís input parameters can be given using HTTP POST or GET requests in x-www urlencoded

format (parameter1=value1&parameter2=value2 etc).





†Main parameter


Main parameter action - what to do?

††††††††††† Action


to display login prompt



to get authorisation form



to get report form



to get parrword forfm for change of password



to send an authorisation request



to show transaction report/list



to change password



to get service list






feedback action in case of sending out feedback to merchant for e -commerce transactions



to get user/merchant management form



to change the processing status of transaction



to browse transaction details










Other important parameters:



††††††††††† id

String up to ..16

User/Merchant user name, must be present with all operations.

††††††††††† password

String up to ..32

User/Merchant password must be present with all password protected operations (if no session key present)

††††††††††† sessionkey

Hex String 34

128 bit session key, will be generated at login, must be present with protected operations





if action=auhorise

††††††††††† transtype


authorization request with x100 message



reversal request



authorization request with x200 message




††††††††††† transclass


transaction class goods (retail)



cash advance


goods unattended

unattended retail (fuel dispenser etc)

††††††††††† mcc

merchant mcc value n4

Optional, if present with request will be used, othervise the MCC value from database will be used

††††††††††† original

original receipt no n5

the original receipt no in case of reversal (transtype=reversal)

††††††††††† pan

n ..19

Card number (PAN)

††††††††††† expdate


Card expiration date (MMYY)




††††††††††† amountmajor


transaction amount in major units with decimals




††††††††††† amountminor


transaction amount in minor units without decimal (optional, will be added to amountmajor)

††††††††††† track1


Card track1 (in case card is read)

††††††††††† track2


Card trcak2† (in case card is read)

††††††††††† trackdata


universal Card track data parameter - track1, track2 or both or pan only. If this parameter will be used then parameters pan and track1 and track2 may not necessary

††††††††††† checkdigits


check digits - the four last digits from card embossing to validate data read from magnetic track, required if track data is read

††††††††††† msgdata

String (..999)

Optional, any useful data can be inserted during transaction (name, address, etc.)




Report parameters:


if action=gettranslist

††††††††††† type






††††††††††† status


transactions already sent for processing



unsent transactions



stopped/blocked transactions



denied transactions



reversed transactions

††††††††††† from


date from

††††††††††† until


date to

††††††††††† fileid


file id




Browse parameters:


if action=browsetransaction

††††††††††† tr.uno


the transaction unique id - uno


















Change of password:




if action=changepass

††††††††††† oldpassword

String 6..16

old valid password

††††††††††† newpassword0

String† 6..16

new password

††††††††††† newpassword1

String† 6..16

repeat new password



E-commerce transaction with e-shop plugin or processor:


To get authrisation form for E-transaction:



††††††††††† id

String up to ..10

Merchant/user id in system, must be presemt with all operations

††††††††††† ecuno


Merchant system unique transaction id for e-commerce transaction

††††††††††† amountmajor

number decimal

Transaction amount provided by merchant/user system in major units with decimals

††††††††††† mac

Hex String

the message mac calculted from id+ecuno+amounmajori (encrypted with merchant key)


Calculation MAC MAC=IDEA(skey, id+ecuno+amountmajor)


where skey - is merchant (secret) key known to merchant and service provider

NB! The total length of parameters must divide by 8 if not trailing padding with spaces (char(32)) needed



E-commerce feedback parameters


(e-commerce feedback message from iPAYServlet to merchant/user system)

††††††††††† id

String up to ..10

merchant/user id

††††††††††† ecuno


the unique transaction number was generated by merchant system

††††††††††† receipt_no

n or null

the receipt number assigned with transaction by iPAYServlet serveri if transaction was sucessful and null if transaction was unsucessful

††††††††††† amountmajor

number decimal

Transaction amount approved in major units with decimals

††††††††††† respcode

AN 2 or AN3

Transaction action code (00 and 000 are† OK other will deny as specified by ISO8583)

††††††††††† actiontext


respcode description text

††††††††††† datetime

date YYYYMMDDhhmmss

transaction date and time

††††††††††† msgdata


additional transaction data (cardholder name etc)

††††††††††† mac

Hex String

message MACc


Calculation of MAC for feedback

MAC=IDEA(skey, id+ecuno+receipt_no+amountmajor+respcode+datetime)


where skey - is merchant (secret) key known to merchant and service provider

NB! The total length of parameters must divide by 8 if not trailing padding with spaces (char(32)) needed