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.
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
| Business Partner | POST URL |
| Cardlink/Cardlink One | https://ecommerce-test.cardlink.gr/vpos/shophandlermpi |
| Nexi | https://alphaecommerce-test.cardlink.gr/vpos/shophandlermpi |
| Worldline | https://eurocommerce-test.cardlink.gr/vpos/shophandlermpi |
| 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. Max decimal digits: 2. Do not use comma in large amounts, e.g. use 10346.78, not 10,346.78. |
| 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 | O | Recommended. 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 | O | Recommended. Billing address zip code (string..16) |
| 14. | billCity | O | Recommended. Billing address city (string..50). Avoid special characters. |
| 15. | billAddress | O | Recommended. Billing address street (string..50). 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 | 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 | 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 | 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 | 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 | 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. Indicative, dummy value for unscheduled recurring master transaction. |
| 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. Indicative, dummy value for unscheduled recurring master transaction. |
| 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..256) |
| 35. | cancelUrl | R | Cancel url where to send payment feedback in case payment has failed or was canceled by user (string..256) |
| 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 | Required for unscheduled recurring with value rcauto=false to be able to execute recurring child through mass payment file or xml api. |
| 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 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
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.
| 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 | Unique merchant shop order id string max length 50. |
| 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 | extData | O | Acquirer defined field may be encoded and contain subfields in format p1=v1&p2=v2.. (url encoded value) string .. 1024 |
| 14 | 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. |
Table 3: Returned message to merchant shop
Note1: 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.
Note2: 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 notification POST
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.
| Counter | Field (HTTP POST parameter) | Required / Optional | Description |
| 1. | version | O/R | Value 2 |
| 2. | mid | R | Merchant id supplied (integer number) max length 30 |
| 3. | orderid | R | Merchant shop order id string max length 45 |
| 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. | Sequence | R | Sequence number or recurring (parent has sequence number 1, the first recurring child will have sequence number 2, etc) |
| 13. | SeqTxId | R | The sequence transaction unique id in system (Integer) |
| 14. | paymentRef | O | Optional end payment system reference or approval code. String 1..64 |
| 15. | 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. |
Table 4: Http Post Response fields with recurring
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 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:
| Counter | Post field | Post field value |
| 1 | version | 2 |
| 2 | mid | 0101119349 |
| 3 | orderid | O170911143656 |
| 4 | status | CAPTURED |
| 5 | orderAmount | 0.12 |
| 6 | currency | EUR |
| 7 | paymentTotal | 0.12 |
| 8 | message | OK, 00 – Approved |
| 9 | riskScore | 0 |
| 10 | payMethod | visa |
| 11 | txId | 926012471 |
| 12 | paymentRef | 138104 |
| 13 | digest | FpwgGyCRwhmF6CWtRFLqfkuQpdPyX8Xh3tJg3E891SA= |
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.
- The concatenated string of the above values is the following:20101119349O170911143656CAPTURED0.12EUR0.12OK, 00 – Approved0visa926012471138104
- By adding the SHARED SECRET, the following string is produced20101119349O170911143656CAPTURED0.12EUR0.12OK, 00 – Approved0visa926012471138104Cardlink1
- 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