Api products
Redirect

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
Method POST
Cardlink URL https://ecommerce-test.cardlink.gr/vpos/shophandlermpi
Alpha Bank URL https://alphaecommerce-test.cardlink.gr/vpos/shophandlermpi
Eurobank URL 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  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) 
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, USD)) 
9. payerEmail  O  Order payer email address (string 1..64) 
10. payerPhone  O  Order  payer   phone  number,  optional  but  strongly recommended (string..30) 
11. billCountry  R  Billing address country code (string 2 ISO 3166-1-alpha-2 code (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..64) 
15. billAddress  R  Billing address street (string..100) 
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 (US, FI, GB)) Optional, required when parameter weight or dimensions are present. 
19. shipState   O/R  Shipping address state (string..50) Optional, required when parameter weight or dimensions are present. 
20.  shipZip  O/R  Shipping address zip code (string..16) Optional, required when parameter  weight or  dimensions are  present. Optionalrequired when parameter weight or dimensions are present 
21. shipCity  O/R  Shipping address city (string..64) Optional, required when parameter weight or dimensions are present. 
22.  shipAddress  O/R  Shipping address street (string..100) Optional, required when parameter weight or dimensions are present. 
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 

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 numbermax 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 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:

HTML
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 with Visa

HTML
<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 value=" type="hidden" />
<input name="orderid" type="hidden" value="O170911143656" />
<input name="orderDesc" type="hidden" value=""Test" />
<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="6900000000" />
<input name="payMethod" type="hidden" value="visa" />
<input name="confirmUrl" type="hidden" value="https://eurocommerce-test.cardlink.gr/vpostestsv4/shops/shopdemo.jsp?cmd=confirm" />
<input name="cancelUrl" type="hidden" value="https://eurocommerce-test.cardlink.gr/vpostestsv4/shops/shopdemo.jsp?cmd=cancel" />
<input name="digest" type="hidden" value="1XbgGLEa9X6RxXgJD1m6dBEsDcaUPVGQ3JuqXjueEU4=" />
</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 shopabout 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 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, USD)) 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 50 
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, USD)) 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. 

 

  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.