Introduction

Cardlink VPOS is an application that is designed for processing merchant payments in ecommerce environment. The input to VPOS are payment requests originating at the merchant shopping solution. These requests are processed by VPOS and the output (transaction approved or declined) is sent back to the merchant shopping solution.

Cardlink VPOS can process payments in two methods. Direct XML or by Redirection to a specific page. This chapter describes the Redirection methodology.

The payment methods that the merchant solution will use (credit, debit cards, Visa, Mastercard etc.) are decided by the merchant and provided that they are supported by Cardlink VPOS, they can be tested in this tool. Cardlink VPOS core design enables multiple types of merchant interfaces to be implemented.

Cardlink Payment Gateway interface for merchant shop

Communication between the Cardlink Payment Gateway and the Merchant shopping cart software can be implemented via HTTP post protocol following the specifications below.

POST request message for payment initiation

Merchant shop request to initiate payment with Cardlink Payment Gateway

The Merchant shopping cart sends to Cardlink e-Commerce via http POST the appropriate HTML code with the relative information of the transaction that starts. The following table describes the parameters of the POST from the payment page to Cardlink Payment Gateway.

POST /authorization

Resource Information

If extension parameters extInstallmentoffset, extInstallmentperiod are present and valid then the request in considered an installment payment (parent).
If extension parameters extRecurringfrequency, extRecurringenddate are present and valid then the request in considered a recurring payment (parent).

Note: Installment parameters and recurring parameters together are not allowed on same request. For this reason the merchant can send:

Either the installment fields:
<input name="extInstallmentoffset" size="3" type="hidden" value="2" /> <input name="extInstallmentperiod" size="3" type="hidden" value="2" />
Or the recurring fields:
<input name="extRecurringfrequency" size="3" type="hidden" value="12" /> <input name="extRecurringenddate" size="8" type="hidden" value="20140712" />

All parameters in the post must be in form default encoding (application/x-www-form-urlencoded) and form must be submitted with utf-8 encoding.
form.action="{supplied Cardlink Payment Gateway service url}"
form.method="POST"
form.enctype="application/x-www-form-urlencoded"
form.accept-charset="UTF-8"

Example of Sale transaction

<form id="form1" accept-charset="UTF-8" action=" https://eurocommerce-test.cardlink.gr/vpos/shophandlermpi" method="POST" name="test">
<input name="version" type="hidden" value="2" />
<input name="mid" type="hidden" value="0101119349" />
<input name="lang" type="hidden" value="en" />
<input name="deviceCategory" type="hidden" value="0" />
<input name="orderid" type="hidden" value="O170911143656" />
<input name="orderDesc" type="hidden" value="Test order some items" />
<input name="orderAmount" type="hidden" value="0.12" />
<input name="currency" type="hidden" value="EUR" />
<input name="payerEmail" type="hidden" value="cardlink@cardlink.gr" />
<input name="payerPhone" type="hidden" value="30-6900000000" />
<input name="billCountry" type="hidden" value="GR" />
<input name="billZip" type="hidden" value="12345" />
<input name="billCity" type="hidden" value="Athens" />
<input name="billAddress" type="hidden" value="Street 45" />
<input name="confirmUrl" type="hidden" value="https://ecommerce-test.cardlink.gr/vpostestsv4/shops/shopdemo.jsp?cmd=confirm" />
<input name="cancelUrl" type="hidden" value="https://ecommerce-test.cardlink.gr/vpostestsv4/shops/shopdemo.jsp?cmd=cancel" />
<input name="digest" type="hidden" value="ybXX2tQkFlxzHM5SjH0oGrD9zms21SUQnwkYaFrnGdc=" />
</form>

Note: The example above includes some required and some optional fields. For your reference and not for technical implementation. For technical implementation please advise Table 1: Http Post Request fields.

 

For Digest Calculation please visit: Digest calculation guide.

POST response message

Return message POST to inform merchant shop about payment success or failure.

The following table describes the parameters of the POST from Cardlink Payment Gateway back to merchant shop.

Table 3: Returned message to merchant shop 

Note 1: When payment is success the message is returned back to the url that merchant has defined as confirmUrl in request. If payment fails or it is canceled the message is returned to cancelUrl parameter provided in merchant request. 

Note 2: For security reasons, each merchant should calculate the digest of the received response message to confirm its validity. The digest value of the response message is different from the one of the initial request.

Note 3: Since the latest Cardlink Payment Gateway version there is also available configurable option that server sends in background delayed (5..120 seconds) independent confirmation message (copy of redirection confirmation) to merchant server without user browser interaction as sometimes user browser may fail to reach back to merchant site. So it is recommended that merchant systems are prepared to handle multiple confirmations for same order properly due this feature and also possible user browser reloads, back buttoning etc. Background confirmation http request can be identified by having user-agent header set to value “Modirum VPOS”.

Recurring transactions POST response message

The following table describes the parameters of the direct POST from Cardlink Payment Gateway back to merchant shop (recurring notifications url) in case of scheduled recurring child is processed by Cardlink server.

Table 4: Http Post Response fields with recurring

Detailed information about recurring transactions can be found here.

Payment statuses (Redirect)

Payment statuses in response message

Table 5: Payment Statuses in Response message

Digest calculation in response message

Merchants may use the received digest to validate the Cardlink Payment Gateway response.

Digest in received message is calculated with the same rules as in request message.

Assuming that the sale transaction of the example was successful and the following field values where returned by Payment Gateway:

Table 6: Sale Example Http Post Response field values 

Note: The above field values are listed in the same order as parameters are listed in table. 

1. The concatenated string of the above values is the following:20101119349O170911143656CAPTURED0.12EUR0.12OK, 00 – Approved0visa926012471138104
2.  By adding the SHARED SECRET, the following string is produced20101119349O170911143656CAPTURED0.12EUR0.12OK, 00 – Approved0visa926012471138104Cardlink1
3. By using base64 and SHA256*

Digest=base64(sha256(utf8bytes(value1|value2|…|secret) ) ) = FpwgGyCRwhmF6CWtRFLqfkuQpdPyX8Xh3tJg3E891SA= 

This is the same as the digest field value the merchant received. 

*For Recurring notification POST, if version=2 is missing, use SHA1

Tokenization Process Overview

The tokenization process will be performed by Cardlink Payment Gateway, under the condition that merchant is activated as Tokenized merchant.

During the first usage of a card from a consumer/payer to Cardlink Payment Gateway, apart from the authorization message, the following (at a high level) should also be performed: The card details (i.e. pan, expiry date) will be forwarded to the Cardlink Tokenization Manager for the creation of the Token, the Token will be returned to the response message received by the merchant and the Token will be stored from the e-shop.

Tokens are calculated by Cardlink Tokenization Manager service and they are being provided to merchant after initial successful payment if the merchant is participating in this extension service (Tokenized merchant).

After the completion of the transaction, it will be stored by merchant’s site for future use.

First time Payment (Registration)

The first-time payment use case covers the scenario that a consumer/payer places an order for the first time. If a consumer/payer uses another credit card for the first time with the same merchant, the same use case applies too. The flow for the first-time payment is:

• After concluding the order in the merchant’s web shop, the customer enters the credit card details to confirm the payment on the payment page
• The Cardlink Payment Gateway forwards the transaction details to the payment network (and all the necessary authentication steps are being performed)
• If the transaction is accepted by the payment network, the Cardlink Payment Gateway (thru the Cardlink Tokenization Manager) tokenizes the PAN and returns the transaction confirmation with the token, the PAN’s 4 last digits & token expiration date back to the merchant
• The merchant stores the above info (instead of the PAN and using possibly an alias that the consumer will define & use for now on).

Figure 1: First-time payment (high-level) diagram

Successive payment

The successive payment use case applies to the scenario where a registered consumer/payer places an order (using the registered card, meaning that the merchant has a token on file for that consumer/payer). The use case also applies for the situation where a consumer/payer has multiple cards (tokens) on file for the given merchant (i.e. the consumer/payer has already registered more than one cards with the same merchant). The flow is:

• The merchant presents (possibly the alias and) the PAN’s 4 last digits to the consumer/payer to select one for executing the payment
• The merchant forwards the payment (with the token) to the Cardlink Payment Gateway
• The Cardlink Payment Gateway (thru Cardlink Tokenization Manager) executes a detokenization with the provided token from the merchant. This results in a PAN and expiry date, which are required for the actual payment transaction
• The Cardlink Payment Gateway forwards the transaction details to the payment network or presents payment page with the prefilled data (pan, expiration date)
• The Cardlink Payment Gateway returns the transaction result back to the merchant with the token used
• The confirmation is presented to the customer.

Figure 2: Successive payment (high-level) diagram

Specification Details

Redirection model

For the initial transaction, the merchant’s request should contain a variable indicating that a Token needs to be retrieved (extTokenOptions), whereas for a secondary transaction that merchant has an already received Token from a previous transaction. The already received Token should be sent in merchant’s request.

The variables extToken ,extTokenPanEnd and extTokenExp will be sent in the response message and they will be considered in the response digest calculation if they have been sent in the response message.

On repeating purchase, the merchant will send the Token in field extToken .

On the payment page the token is decoded and displayed as masked pan in the card number box and the expiry date is prefilled as well.

There are specific parameters that allow for the smoother model operation, like the CVV flag. Τhe merchant will mutually agree with the Bank to set it and allow for the consumer/payer not to fill the CVV in the secondary transactions.
The payment page display/existence is also a parameter and will also be defined at merchant level.

The previous options, if used together, will allow for the “one-click checkout” experience for the consumer/payer side.

Merchant request (initiate payment)

The Merchant shopping cart sends to Cardlink Payment Gateway via http POST the appropriate HTML code with the relative information of the transaction that starts. The following table describes the parameters of the POST from the payment page to Cardlink Payment Gateway.

*Tokenizer: Tokenization without Authorization

Response message (inform merchant for payment execution)

The following table describes the parameters of the POST from Cardlink Payment Gateway back to merchant shop.

Merchant request (tokenized payment) 

Response message (tokenized payment)

The following table describes the parameters of the POST from Cardlink Payment Gateway back to merchant shop.

Payment statuses (Redirect with token)

Table : Payment Statuses in Response message

Digest is the safety valve for the transactions between Company and Cardlink e- Commerce and vice versa. Digest is one of the fields that the payment page sends and certifies the safe data transferring between the company and the Bank.

Digest should be calculated and validated for both the request and the response message. The digest value of the response message is different from the one of the initial request.

Requirements for Digest creation:

The field values that the POST form sends (post_fields_values).

Based on the values of the payment page fields, the company needs to create a string with all the field values sent by payment page in the bank system.

Concatenate all the values of all the possible fields listed in the table, the same order as parameters are listed in Payment page fields table.

If a parameter is omitted, empty string is concatenated.

The string must be encoded using UTF – 8 char encoding. This can be achieved by using the functions provided by the language that implements the solution (eg utf8_encode for PHP or Encoding.Convert for .NET).

The SHARED SECRET

The bank communicates to every merchant a unique code which is called SHARED SECRET. The SHARED SECRET must be included at the end of the previous string.

3) The base64 and sha-256 functions.

Digest in the request POST (and in the return POST) is calculated by the following rule:

1. Concatenate all the values of all the possible fields listed in the table, the same order as parameters are listed in Payment page fields table.
2. Add SHARED SECRET
3. Encryption and Encoding using base64 and sha 256* functions
   • Calculate SHA256 digest of step 1 (using of UTF-8 char encoding when converting string to bytes).
   • Return the SHA256 digest.
   • Encode digest bytes with Base64 encoding.

*For Recurring notification POST, if version=2 is missing, use SHA1

Digest=base64( sha256( utf8bytes(value1|value2|…|secret) ) )

Note: ‘|’ indicates concatenation of data in formula and must not be added to data.

Never implement the digest calculation in browser using javascipt or similar as this way you expose your shared secret to the world. Only implement it in server side executed code as (jsp/servlet/asp/php etc).

The parameters that the merchant must include in post request are the following:

The sequence of those parameters will be used to calculate the digest parameter in the next steps

if you have trouble calculating the digest, please use the tool.

Example
In the below example of Sale Transaction, the digest value sent was calculated as «ybXX2tQkFlxzHM5SjH0oGrD9zms21SUQnwkYaFrnGdc=». According to the digest calculation rules this value is delivered as follows:

<form id="form1" accept-charset="UTF-8" action=" https://eurocommerce-test.cardlink.gr/vpos/shophandlermpi" method="POST" name="test">
<input name="version" type="hidden" value="2" />
<input name="mid" type="hidden" value="0101119349" />
<input name="lang" type="hidden" value="en" />
<input name="deviceCategory" type="hidden" value="0" />
<input name="orderid" type="hidden" value="O170911143656" />
<input name="orderDesc" type="hidden" value="Test order some items" />
<input name="orderAmount" type="hidden" value="0.12" />
<input name="currency" type="hidden" value="EUR" />
<input name="payerEmail" type="hidden" value="cardlink@cardlink.gr" />
<input name="payerPhone" type="hidden" value="30-6900000000" />
<input name="billCountry" type="hidden" value="GR" />
<input name="billZip" type="hidden" value="12345" />
<input name="billCity" type="hidden" value="Athens" />
<input name="billAddress" type="hidden" value="Street 45" />
<input name="confirmUrl" type="hidden" value="https://ecommerce-test.cardlink.gr/vpostestsv4/shops/shopdemo.jsp?cmd=confirm" />
<input name="cancelUrl" type="hidden" value="https://ecommerce-test.cardlink.gr/vpostestsv4/shops/shopdemo.jsp?cmd=cancel" />
<input name="digest" type="hidden" value="ybXX2tQkFlxzHM5SjH0oGrD9zms21SUQnwkYaFrnGdc=" />
</form>

1) Concatenate all the values of all the possible fields listed in the table, the same order as parameters are listed in Payment page fields table.

So, the concatenated string of the above values is the following:

20101119349en0O170911143656Test order some items0.12EURcardlink@cardlink.gr30-6900000000GR12345AthensStreet 45https://ecommerce- test.cardlink.gr/vpostestsv4/shops/shopdemo.jsp?cmd=confirmhttps://ecommerce- test.cardlink.gr/vpostestsv4/shops/shopdemo.jsp?cmd=cancel

Note: The concatenated string must contain all the values the merchant has sent, not just the required ones (the above string contains the optional values of lang and deviceCategory).

2) Add SHARED SECRET

SHARED SECRET is the password between the bank and the merchant and must be added at the end of the previous string. Assume SECRET is «Cardlink1», then the produced sting is the following:

20101119349en0O170911143656Test order some items0.12EURcardlink@cardlink.gr30-6900000000GR12345AthensStreet 45https://ecommerce- test.cardlink.gr/vpostestsv4/shops/shopdemo.jsp?cmd=confirmhttps://ecommerce- test.cardlink.gr/vpostestsv4/shops/shopdemo.jsp?cmd=cancelCardlink1

3) Encryption and Encoding using base64 and sha256 functions

The final step of digest calculation is the use of base64 and sha256 functions according to the following rule:

Digest=base64( sha256( utf8bytes(value1|value2|…|secret) ) )

This produces the following result:

ybXX2tQkFlxzHM5SjH0oGrD9zms21SUQnwkYaFrnGdc=

if you have trouble calculating the digest, please use the tool.