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 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:
- 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.
- 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.
*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
| Counter | Field (HTTP POST parameter) | Required / Optional | Description |
|
|
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) |
| 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))
For Kosovo, use Serbia’s country code RS |
| 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) |
| 15. | billAddress | R | Billing address street (string..50) |
| 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)). 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). 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. |
| 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. |
| 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 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. | var1 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 37. | var2 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 38. | var3 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 39. | var4 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 40. | var5 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 41. | var6 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 42. | var7 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 43. | var8 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 44. | var9 | O | Optional merchant and acquirer agreed free variable type string ..255 |
| 45. | 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). |
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 «NCGHNiNtLXY/aMLGSQrogsjlPtPucqQF6NAk1y0+FCg=». 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="NCGHNiNtLXY/aMLGSQrogsjlPtPucqQF6NAk1y0+FCg=" />
</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.
| Counter | Post Field | Post field value | |
| 1 | version | 2 | |
| 2 | mid | 0101119349 | |
| 3 | lang | en | |
| 4 | deviceCategory | 0 | |
| 5 | orderid | O170911143656 | |
| 6 | orderDesc | Test order some items | |
| 7 | orderAmount | 0.12 | |
| 8 | currency | EUR | |
| 9 | payerEmail | cardlink@cardlink.gr | |
| 10 | payerPhone | 30-6900000000 | |
| 11 | billCountry | GR | |
| … | … | … | |
| 13 | billZip | 12345 | |
| 14 | billCity | Athens | |
| 15 | billAddress | Street 45 | |
| … | … | … | |
| … | … | … | |
| … | … | … | |
| … | … | … | |
| 34 | confirmUrl | https://ecommerce- test.cardlink.gr/vpostestsv4/shops/shopdemo. jsp?cmd=confirm | |
| 35 | cancelUrl | https://ecommerce- test.cardlink.gr/vpostestsv4/shops/shopdemo. jsp?cmd=cancel |
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:
NCGHNiNtLXY/aMLGSQrogsjlPtPucqQF6NAk1y0+FCg=
if you have trouble calculating the digest, please use the tool.