Developer E-commerce

 

 

There are two requirements needed to fulfill, before the testing and development can start:

1. Ecommerce contract has been made with the acquirer bank

2. You have received email with test account details (Nets Estonia creates test account after receiving information from acquirer bank)

​​​​​​The iPay (Nets Estonia ecommerce solution) test environment is a copy of the live environment. You can explore and learn how our systems function without worrying about messing up your real account at iPay. 

 

Generally you need to implement two data flows to iPay server:

1. Payment request to the iPay server. (Initiator your website, receiver "iPay server").

2. Payment verification, this is handled by your web service. (Initiator "iPay servlet", receiver your website)

 

1. Payment request. 

First you need to construct http(s) protocol type request, use POST (recommended) meth​od.  Payment request should be sent against iPay server - https://pos.estcard.ee/test-pos/iPay​servlet. Request parameters and descriptions presented in below table: 

 

Table 1. Request parameters

 

​Request parameter​Description​Format​Sample value
​lang​interface language ISO 639-1​char(2)​et
​action​iPay action name​int(3)​gaf
​ver​iPay protocol version​int(3)​004
​id​your web service id (available payment service contract)​char(10)​B51D77CEE0
​ecuno​time stamp [YYYYMM] + random num. between 100000-999999int(12)​201301214119
​eamount​payment amount (cents)​int(12)​000000000019
​cur​payment currency ISO-421​7​char(3)​EUR
​datetime​time stamp [YYYYMMDDhhmmss]ISO-860​1​​int(14)​20130103094052
​charencoding​character encoding​char​UTF-8
​feedbacku​rl​feedback url​char(128)​http://www.wkiosk.com​/pic/ecom/feedBack.php​
​delivery​delivery symbol​char(1)​S
​additionalinfo​additional info (Order no, desc, etc)​char (128)​ticket:12345;weight:3kg
​macsigned result ​in HEX format​-​​350c16ae4016db9fac2f5c374f60a857lf56
fd4cf6f108e9f39d59b7c96e9f378a85c2d2
d8bf02b2cfe5e78a1b97984d405f359e1e28
49de3822430596a83b7a1dbe0f78f605e26d
8aae39f69e4dbd25387294e8bf611d323b32
8bc300bf7a188bfe8c9e04c67e56bade1e3ea19e

 

* Data included in "mac" value. 

"mac" - Signed result in HEX format. Communication protocol with iPay server is unique. First is needed to construct [data] string, after that created string should be signed.

 

Example of data string from Table 1. values:

 

data = ver+id+ecuno+eamount+cur+datetime+feedBackUrl+delivery+additionalinfo

data = 004B51D77CEE201301214119000000000019EUR20130103094052http://www.wkiosk.com/pic/ecom/feedBack.php<-128->S<-128->ticket:12345;weight:3kg​


Message signature fields must be filled to the maximum length, before the signature calculation and verification. To achieve this, the numerical fields must be filled from left with "0" (zero) and string values must be filled with spaces from the right (ASCII code 20H).

 

After message is constructed, string should be signed with the private key. Test environment private key available here - mytestprivat.key​

 

Next, we need to transform signed string to HEX format. Produced HEX format hash should be added into request package - parameter name is "mac".

 

*Example of creating the HEX format from signed string with using OPENSSL. 

 

 OPENSS​L is used, because OPENSSL algorithms are implemented in almost all programming languages.

To make signature and take it to a HEX format: 

echo -n 'data' | openssl dgst -sha1 -sign mytestprivat.key -hex

Commands output is "mac", which is needed to add to request package and sent to the iPay server. We see generated "mac" in table 1 row "mac".

 

Short description of OPENSSL parameters:

" dgst -sha1" - define hash with SHA​1​ method

" -sign mytestprivat.key" - sign with private key mytestprivat.key

" -hex" - convert signature to hex format

 

 

2. Payment verification from iPay server to "feedBackUrl". 

 

iPay server will send feedback into your defined "feedBackUrl". the following request parameters their descriptions in table 2.​

 

Table 2.Request parameters

 

​Request parameter​Description​Format​Sample value
​ver​iPay protocol version​int(3)​004
​id​your web service id (available payment service contract)​char(10)​B51D77CEE0
​ecuno​time stamp [YYYYMM] + random num. between 100000-999999​int(12)​201301214119
​receipt_no​receipt counter​int(6)​000012
​eamount​payment amount (cents)​int(12)​000000000019
​cur​payment currency ISO-4217​char(3)​EUR
​respcode​respond code (000-ok)int(3)​000
​datetime​time stamp format [YYYYMMDDhhmmss] ISO-860​​1int(14)​20130103094331
​msgdata​payment description - customer enter, customer name​char(40)​nipitiri
​actiontext​response code description​char(40)​OK, approved
​macsigned result in HEX format​-​2D76944D9A057684609602DB7F
DE0872D4DEDD5B109FE9E4246E
475D8BDD13C438E93C6CA4FBC
9FBB1F6A96FB515B0C48F5387C
C25956A86BF9B02DFCE6C91E5C
913925D9DBC8A340E43FBAD5C9
5FDBF304A0E10BD56837DFBC9B
55F01DBCBB777D2DE96EEFEFAD
C014419B35E20C201CF721D4FD
4EF9FF895037F0466E661B
 

 

data = ver+id+ecuno+receipt_no+eamount+cur+respcode+datetime+msgdata+actiontext

data = [004B51D77CEE0201301214119000013000000000019EUR00020130103094331nipitiri         OK, approved           ]


Message signature fields must be filled to the maximum length, before the signature calculation and verification. To achieve this, the numerical fields must be filled from the left with "0" (zero) and string values must be filled with spaces from the right (ASCII code 20H).​

​ 

Now will be checked the signed result, for that is needed Test environment public key -  ecomtestpublic.ke​y

 

echo -n '$mac' | xxd -r -p > /tmp/data.txt.sign; echo -n '$data'

                         | openssl dgst -sha1 -verify ecomtestpublic.key -signature /tmp/data.txt.sign

 

We are waiting for the answer: Verified OK. 

 

*"Feedback". Feedback provides for merchant and customers more security. Nets Estonia always check that merchant feedback URL is working and if feedback feature for some reason does not work, then Nets Estonia have the right to close your payment service account in live environment.

 

*Public and private key generation. In live environment you need to use in web service private and public key.

 

Private key generation command: openssl genrsa -out myprivate.key 1024

Public key generation command: openssl rsa -in myprivate.key -pubout > mypublic.key

 

If payment process is tested in test environment, then is needed to sent "mypublic.key" to Nets Estonia (webpos@estcard.e​e)

We will record your public key at iPay server.

 

*Programming code.

NB! Examples of code are simplified case studies with the aim of explaining the ecom communication. These examples do not specifically address the specifics of the webstore platforms.​ 

Reference code samples need to be reworked by the developer to integrate with e-shop and to ensure the "good practices" of software.


OPENSSL over php:

payment - testPos.php.tx​​t

feedback - feedBack.php.txt

 

PHP code base:

payment - testPosPHP.php.txt

payment - ​

feedback - feedBackPHP.php.tx​t

refactored code - refaktooritudPHP.tx​t​

 

JAVA servlet standard:

payment and feedback - PaymentServlet.java.tx​t​

 

*After successful testing, please send notification to e-mail: webpos@estcard.ee and you receive further information.