Overview

This page provides overview and details about the function and interfaces of Cardlink Tokenization along with Cardlink Payment Gateway.

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.

Use Cases

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 shop 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

Return message POST (inform merchant for payment execution)

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

Merchant shop request (tokenized payment) 

Return message POST (inform merchant for payment execution).

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

Payment statuses in response message

Table : Payment Statuses in Response message

Calculation of the Digest

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

Requirements for Digest creation:

1. 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.

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
2. If a parameter is omitted, empty string is concatenated.
3. 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 PHPor Encoding.Convert for .NET).

2.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
2. Add SHARED SECRET
3. Encryption and Encoding using base64 and sha-256 functions
   1. Calculate SHA256 digest of step 1 (using of UTF-8 char encoding when converting string to bytes).
   2. Return the SHA256 digest.
   3. Encode digest bytes with Base64 encoding.

Digest=base64( sha-256( 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 javascript 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/phpetc).

For Digest Calculation please visit: Digest Calculation Guide