Redirect with token
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.
| Counter | Field (HTTP POST parameter) | Required / Optional | Description |
| 1. | version | R | Value = 2 |
| 2. | mid | R | Merchant id supplied (integer number) will be supplied to merchant, max length 30 |
| 3. | lang | O | Language selection for payment page (ISO 639-1 language code en, fi, sv…) |
| 4. | deviceCategory | O | Optional user device category (default 0 www browser, 1 mobile browser) |
| 5. | orderid | R | Unique merchant shop order id provided by merchant shop max length 50 chars (string 1..50 – only letters and numbers are accepted with no any space between them). For recurring transactions max length is 45 chars. |
| 6. | orderDesc | R | Order description text (string 1..128 – special characters are accepted ) |
| 7. | orderAmount | R | Order amount (decimal number >0.0) max length 15 with decimal point. Amount is set to 0.0 for Tokenizer* |
| 8. | currency | R | Order amount currency (string 3 ISO ISO 4217 alphabetic code (EUR)) |
| 9. | payerEmail | R | Order payer email address (string 1..64). Format name@domain.tld |
| 10. | payerPhone | O | Order payer phone number. Format • cc: 1–3 characters • subscriber: variable, maximum 15 characters |
| 11. | billCountry | R | Billing address country code (string 2 ISO 3166-1-alpha-2 code (GR,US, FI, GB)). |
| 12. | billState | O | Billing address state (str 2 3166-2 country subdivision code). this value only applies to countries that have states (e.g USA). For Greece, strongly recommended to be omitted |
| 13. | billZip | R | Billing address zip code (string..16) |
| 14. | billCity | R | Billing address city (string..50). Recommended to avoid special characters. |
| 15. | billAddress | R | Billing address street (string..50). Recommended to avoid special characters. |
| 16. | weight | O | Order shipping weight (kg) if item is shippable and shipping needs to be calculated by Cardlink Payment Gateway (decimal number >0) max length 12 with decimal point) |
| 17. | dimensions | O | Order shipping dimensions (mm) in format width:height:depth for example a box 200:200:200 (string..25) can be used for shipping calculation if implemented so |
| 18. | shipCountry | O/R | Shipping address country code (string 2 ISO 3166-1-alpha-2 code (GR, US, FI, GB)) Optional, recommended when parameter weight or dimensions are present or when shipping of goods has to be made. |
| 19. | shipState | O/R | Shipping address state (string..50) Optional, recommended when parameter weight or dimensions are present or when shipping of goods has to be made. This value only applies to countries that have states (e.g USA). For Greece, strongly recommended to be omitted. |
| 20. | shipZip | O/R | Shipping address zip code (string..16). Optional, recommended when parameter weight or dimensions are present or when shipping of goods has to be made. |
| 21. | shipCity | O/R | Shipping address city (string..50) Optional, recommended when parameter weight or dimensions are present or when shipping of goods has to be made. Recommended to avoid special characters. |
| 22. | shipAddress | O/R | Shipping address street (string..50) Optional, recommended when parameter weight or dimensions are present or when shipping of goods has to be made. Recommended to avoid special characters. |
| 23. | addFraudScore | O | Incoming starting risk score (integer) max length 12 |
| 24. | maxPayRetries | O | Maximum payment retries allowed before user is sent back to merchant, overrides specific profile setting if present (integer) max length 2 |
| 25. | reject3dsU | O | Should 3-D Secure return U status, merchant has option of continuing the transaction without liability shift or reject the transaction. >If this value is true, the transaction will not be accepted. (string 1 Y/N) |
| 26. | payMethod | O | For pre selection of payment method. Paymethod id, can be used to preselect payment method at merchant site, so user cannot select other payment method later (string..20), exact values will depend of implemented methods on service provider side. |
| 27. | trType | O | Optional transaction type default assumed payment, valid values 1 – payment, 2 – pre authorization (applicable only to card payments only), 8 – tokenizer |
| 28. | extInstallmentoffset | O | Optional. In case installments are supported by the processing system then this parameter of installments can be used to indicate initial offset in months when first payment will be submitted (by acquirer). Applicable for card payments only. Integer max length 3. Currently, should have value 0. |
| 29. | extInstallmentperiod | O/R | Optional, required in case previous parameter is present. In case installments are supported by the processing system then this parameter of installments is used to indicate the number of payments/months the merchant requests for installments. Applicable for card payments only. Value must be >1. Max length 3 Installment parameters and recurring parameters together are not allowed on same request |
| 30. | extRecurringfrequency | O | Optional. In case recurring payments are supported by the processing system then this parameter can be used to indicate frequency of recurring payments, defines minimum number of days between any two subsequent payments .The number of days equal to 28 is special value indicating that transactions are to be initiated on monthly basis. Applicable for card payments only. Max length 3 |
| 31. | extRecurringenddate | O/R | Optional, required in case previous parameter is present. In case recurring payments are supported by the processing system then this parameter can be used to indicate date after which recurring ends and no more transactions no more transactions are initiated. The format is YYYYMMDD. Applicable for card payments only. Installment parameters and recurring parameters together are not allowed on same request. |
| 32. | blockScore | O | Optional block score parameter that will be used to block the transaction if transaction riskScore reaches this value or above. (Positive Integer number) max length 9. |
| 33. | cssUrl | O | The absolute or relative (to Cardlink Payment Gateway location on server) url of custom CSS stylesheet, to be used to display payment page styles. (string..128) Note: if absolute and payment page is SSL secured make sure the url is also SSL secured as browsers will not show unsecure element object warning. |
| 34. | confirmUrl | R | Confirmation url where to send payment confirmation in case payment was successful (string..128) |
| 35. | cancelUrl | R | Cancel url where to send payment feedback in case payment has failed or was canceled by user (string..128) |
| 36. | extTokenOptions | O | if merchant requests token value should be 100 |
| 37. | var1 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 38. | var2 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 39. | var3 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 40. | var4 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 41. | var5 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 42. | var6 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 43. | var7 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 44. | var8 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 45. | var9 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 46. | digest | R | Message digest to ensure and verify message security and integrity. SHA256 digest of all the field values above concatenated together with the shared secret (see section Calculation of the Digest). |
*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.
| Counter | Field (HTTP POST parameter) | Required / Optional | Description |
| 1. | version | R | Value = 2 |
| 2. | mid | R | Merchant id supplied (integer number) max length 30 |
| 3. | orderid | R | Merchant shop order id string max length 50. For recurring transactions, max length 45 chars. |
| 4. | status | R | Payment status (string..16) see section 2.4 payment statuses |
| 5. | orderAmount | R | Order amount (decimal number >0.0) same as in request |
| 6. | currency | R | Order amount currency (string 3, ISO ISO 4217 alphabetic code (EUR)) same as in request |
| 7. | paymentTotal | R | Order amount plus fees and shipping and additional service charges if applicable (decimal number >0,0) Required when payment was a success, can be omitted when payment was failed or canceled |
| 8. | message | O | Optional message (string..128) can provide optional information about payment or error description. |
| 9. | riskScore | O | Optional information about the possible risk with transaction (integer number) |
| 10. | payMethod | O | Optional information about payment method used to complete transaction (string20).Is present only when payment was success |
| 11. | txId | O | Optional system assigned transaction reference id (integer number) |
| 12. | paymentRef | O | Optional end payment system reference or approval code. String 1..64 |
| 13. | extToken | O | If merchant requested tokenization then on successful payment token value of card used will be returned. |
| 14. | extTokenPanEnd | O | If merchant requested tokenization and tokenization enabled then on successful payment last 4 digits of tokenized pan are returned. |
| 15. | extTokenExp | O | If merchant requested tokenization and tokenization enabled then on successful token payment, token expiration is returned in format YYYYMMDD |
| 16. | digest | R | Message digest to ensure and verify message security and integrity. SHA256 digest of all the field values above concatenated together with the shared secret. |
Merchant shop request (tokenized payment)
| Counter | Field (HTTP POST parameter) | Required / Optional | Description |
| 1. | version | R | Value = 2 |
| 2. | mid | R | Merchant id supplied (integer number) will be supplied to merchant, max length 30 |
| 3. | lang | O | Language selection for payment page (ISO 639-1 language code en, fi, sv…) |
| 4. | deviceCategory | O | Optional user device category (default 0 www browser, 1 mobile browser) |
| 5. | orderid | R | Unique merchant shop order id provided by merchant shop max length 50 chars (string 1..50 – only letters and numbers are accepted with no any space between them). For recurring transactions, max length 45 chars. |
| 6. | orderDesc | R | Order description text (string 1..128 – special characters are accepted ) |
| 7. | orderAmount | R | Order amount (decimal number >0.0) max length 15 with decimal point |
| 8. | currency | R | Order amount currency (string 3 ISO ISO 4217 alphabetic code (EUR)) |
| 9. | payerEmail | R | Order payer email address (string 1..64). Format name@domain.tld |
| 10. | payerPhone | O | Order payer phone number. Format • cc: 1–3 characters • subscriber: variable, maximum 15 characters |
| 11. | billCountry | R | Billing address country code (string 2 ISO 3166-1-alpha-2 code (GR, US, FI, GB)) |
| 12. | billState | O | Billing address state (str 2 3166-2 country subdivision code). this value only applies to countries that have states (e.g USA) |
| 13. | billZip | R | Billing address zip code (string..16) |
| 14. | billCity | R | Billing address city (string..50). Recommended to avoid special characters. |
| 15. | billAddress | R | Billing address street (string..50). Recommended to avoid special characters. |
| 16. | weight | O | Order shipping weight (kg) if item is shippable and shipping needs to be calculated by Cardlink Payment Gateway (decimal number >0) max length 12 with decimal point) |
| 17. | dimensions | O | Order shipping dimensions (mm) in format width:height:depth for example a box 200:200:200 (string..25) can be used for shipping calculation if implemented so |
| 18. | shipCountry | O/R | Shipping address country code (string 2 ISO 3166-1-alpha-2 code (GR, US, FI, GB)) Optional, recommended when parameter weight or dimensions are present or when shipping of goods has to be made. |
| 19. | shipState | O/R | Shipping address state (string..50). Recommended when parameter weight or dimensions are present or when shipping of goods has to be made. This value only applies to countries that have states (e.g USA). For Greece, strongly recommended to be omitted. |
| 20. | shipZip | O/R | Shipping address zip code (string..16). Optional, recommended when parameter weight or dimensions are present or when shipping of goods has to be made. |
| 21. | shipCity | O/R | Shipping address city (string..50). Recommended when parameter weight or dimensions are present or when shipping of goods has to be made. Recommended to avoid special characters. |
| 22. | shipAddress | O/R | Shipping address street (string..50). Recommended when parameter weight or dimensions are present or when shipping of goods has to be made. Recommended to avoid special characters. |
| 23. | addFraudScore | O | Incoming starting risk score (integer) max length 12 |
| 24. | maxPayRetries | O | Maximum payment retries allowed before user is sent back to merchant, overrides specific profile setting if present (integer) max length 2 |
| 25. | reject3dsU | O | Should 3-D Secure return U status, merchant has option of continuing the transaction without liability shift or reject the transaction. >If this value is true, the transaction will not be accepted. (string 1 Y/N) |
| 26. | payMethod | O | For pre selection of payment method. Paymethod id, can be used to preselect payment method at merchant site, so user cannot select other payment method later (string..20), exact values will depend of implemented methods on service provider side. |
| 27. | trType | O | Optional transaction type default assumed payment, valid values 1 – payment, 2 – pre authorization (applicable only to card payments only) |
| 28. | extInstallmentoffset | O | Optional. In case installments are supported by the processing system then this parameter of installments can be used to indicate initial offset in months when first payment will be submitted (by acquirer). Applicable for card payments only. Integer max length 3. Currently, should have value 0. |
| 29. | extInstallmentperiod | O/R | Optional, required in case previous parameter is present. In case installments are supported by the processing system then this parameter of installments is used to indicate the number of payments/months the merchant requests for installments. Applicable for card payments only. Value must be >1. Max length 3 Installment parameters and recurring parameters together are not allowed on same request. |
| 30. | extRecurringfrequency | O | Optional. In case recurring payments are supported by the processing system then this parameter can be used to indicate frequency of recurring payments, defines minimum number of days between any two subsequent payments .The number of days equal to 28 is special value indicating that transactions are to be initiated on monthly basis. Applicable for card payments only. Max length 3 |
| 31. | extRecurringenddate | O/R | Optional, required in case previous parameter is present. In case recurring payments are supported by the processing system then this parameter can be used to indicate date after which recurring ends and no more transactions no more transactions are initiated. The format is YYYYMMDD. Applicable for card payments only. Installment parameters and recurring parameters together are not allowed on same request. |
| 32. | blockScore | O | Optional block score parameter that will be used to block the transaction if transaction riskScore reaches this value or above. (Positive Integer number) max length 9. |
| 33. | cssUrl | O | The absolute or relative (to Cardlink Payment Gateway location on server) url of custom CSS stylesheet, to be used to display payment page styles. (string..128) Note: if absolute and payment page is SSL secured make sure the url is also SSL secured as browsers will not show unsecure element object warning. |
| 34. | confirmUrl | R | Confirmation url where to send payment confirmation in case payment was successful (string..128) |
| 35. | cancelUrl | R | Cancel url where to send payment feedback in case payment has failed or was canceled by user (string..128) |
| 36. | extTokenOptions | O | · Value = 100 Displaying payment page with prefilled card data and 3D authentication required. (extToken field should be sent for tokenized payments)· Value = 110 Auto payment without displaying payment page and 3D authentication required. (extToken field should be sent for tokenized payments) |
| 37. | extToken | O | Generated card token value |
| 38. | var1 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 39. | var2 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 40. | var3 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 41. | var4 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 42. | var5 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 43. | var6 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 44. | var7 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 45. | var8 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 46. | var9 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 47. | digest | R | Message digest to ensure and verify message security and integrity. SHA256 digest of all the field values above concatenated together with the shared secret (see section Calculation of the Digest). |
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.
| Counter | Field (HTTP POST parameter) | Required / Optional | Description |
| 1. | version | R | Value=2 |
| 2. | mid | R | Merchant id supplied (integer number) max length 30 |
| 3. | orderid | R | Merchant shop order id string max length 50. For recurring transactions, max length 45 chars. |
| 4. | status | R | Payment status (string..16) see section Payment statuses in response message |
| 5. | orderAmount | R | Order amount (decimal number >0.0) same as in request |
| 6. | currency | R | Order amount currency (string 3, ISO ISO 4217 alphabetic code (EUR)) same as in request |
| 7. | paymentTotal | R | Order amount plus fees and shipping and additional service charges if applicable (decimal number >0,0) Required when payment was a success, can be omitted when payment was failed or canceled |
| 8. | message | O | Optional message (string..128) can provide optional information about payment or error description. |
| 9. | riskScore | O | Optional information about the possible risk with transaction (integer number) |
| 10. | payMethod | O | Optional information about payment method used to complete transaction (string20).Is present only when payment was success |
| 11. | txId | O | Optional system assigned transaction reference id (integer number) |
| 12. | paymentRef | O | Optional end payment system reference or approval code. String 1..64 |
| 13. | extToken | O | If payment is successful and token value of card used will be returned. |
| 14. | extTokenPanEnd | O | If payment is successful, last 4 digits of tokenized pan are returned. |
| 15. | extTokenExp | O | If merchant requested tokenization and tokenization enabled then on successful token payment, token expiration is returned in format YYYYMMDD |
| 16. | digest | R | Message digest to ensure and verify message security and integrity. SHA256 digest of all the field values above concatenated together with the shared secret. |
Payment statuses in response message
| AUTHORIZED, CAPTURED | Payment was successful (accept order) |
| CANCELED | Payment failed, user canceled the process (deny order) |
| REFUSED | Payment failed, payment was denied for card or by bank (deny order) |
| ERROR | Non recoverable system or other error occurred during payment process (deny order) |
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:
- 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
- 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 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:
- Concatenate all the values of all the possible fields listed in the table, the same order as parameters are listed in Payment page fields
- Add SHARED SECRET
- 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.
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