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¶meter2=value2 etc).
|
Parameter |
Value(s) |
Description |
|
Main parameter |
|
Main parameter action - what to do? |
|
Action |
Login |
to display login prompt |
|
|
getauthform |
to get authorisation form |
|
|
getlistform |
to get report form |
|
|
getpassform |
to get parrword forfm for change of password |
|
|
authorise |
to send an authorisation request |
|
|
gettranslist |
to show transaction report/list |
|
|
changepass |
to change password |
|
|
getservices |
to get service list |
|
|
logoff" |
väljumine |
|
|
feedback |
feedback action in case of sending out feedback to merchant for e -commerce transactions |
|
|
managemerchant |
to get user/merchant management form |
|
|
updatetransactions |
to change the processing status of transaction |
|
|
browsetransaction |
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 |
|
Parameter |
|
if action=auhorise |
|
transtype |
authorisation |
authorization request with x100 message |
|
|
reversal |
reversal request |
|
|
sms_authorisation |
authorization request with x200 message |
|
|
|
|
|
transclass |
goods |
transaction class goods (retail) |
|
|
cash |
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 |
n4 |
Card expiration date (MMYY) |
|
|
|
|
|
amountmajor |
..n10 |
transaction amount in major units with decimals |
|
|
|
|
|
amountminor |
..n2 |
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 |
summary |
|
|
|
detail |
|
|
status |
sent |
transactions already sent for processing |
|
|
unsent |
unsent transactions |
|
|
blocked |
stopped/blocked transactions |
|
|
denied |
denied transactions |
|
|
reversed |
reversed transactions |
|
from |
date YYYYMMDD |
date from |
|
until |
date YYYYMMDD |
date to |
|
fileid |
n5 |
file id |
|
|
|
|
|
Browse parameters: |
|
if action=browsetransaction |
|
tr.uno |
|
the transaction unique id - uno |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Change of password:
|
Parameters: |
|
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: |
action=getauthform |
|
|
id |
String up to ..10 |
Merchant/user id in system, must be presemt with all operations |
|
ecuno |
..int6 |
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 |
action=feedback |
(e-commerce feedback message from iPAYServlet to merchant/user system) |
|
id |
String up to ..10 |
merchant/user id |
|
ecuno |
..int6 |
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 |
String |
respcode description text |
|
datetime |
date YYYYMMDDhhmmss |
transaction date and time |
|
msgdata |
String |
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