XML (direct) model requires PCI DSS certification.
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 Direct XLM methodology and it should be noted that the PCI Compliance is a pre-requisite for this one. More information about PCI Compliance can be accessed here.
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.
Merchants can easily attach their look and feel to payment pages by supplying their own custom CSS stylesheet.
This document describes the newest versions (4.1 and 2.1) of interfaces based on RSA SHA256 signature security (4.1) and shared secret based SHA2-256 digest (2.1).
XML API Interface
The XML API interface plugin enables merchants using their own payment pages hosted in their system to directly access VPOS by using XML messaging.
XML Messaging is using request real time and response messages in the same request/response cycle. In request message merchant provides payment and order info and in response messages VPOS indicates the result of the action performed. By default the merchant should receive the response message within 30 seconds maximum.
Root element of request and response messages is VPOS
Current version of XML API is 4.1 and 2.1 that is copy of 4.1 only difference is that message security is in 2.1 ensured by a Digest element computed from canonicalized Message element appended with shared sercret.
The request message general structure:
<VPOS>
<Message version=”4.1″messageId=”M12345″timeStamp=”” lang=”en”>
<xxxxxRequest>
<Authentication>… </Authentication>
<OrderInfo>…</OrderInfo>
<PaymentInfo>
<ThreeDSecure>…</ThreeDSecure>
</PaymentInfo>
</xxxxxRequest>
</Message>
<Signature>…</Signature>
</Merchant-VPOS>
The response message general structure:
<VPOS>
<Message version=”4.1″ messageId=”M12345″>
<xxxxxResponse>
<OderId></OrderId/>
<OrderAmount><OrderAmount/>
<PaymentTotal></PaymentTotal>
<Currency></Currency>
<Status></Status>
<TxId></TxId>
<Sequence></Sequence>
<SeqTxId></SeqTxId>
<PaymentRef></PaymentRef>
<RiskScore></PaymentRef>
<ErrorCode></ErrorCode>
<Description></Description>
</xxxxxResponse>
</Message>
<Signature>..</Signature>
</VPOS>
The general error message structure (returned in case request: message was unparseable or
unvalidatable)
<VPOS>
<Message version=”1.0″ messageId=”M12345″>
<ErrorMessage>
<ErrorCode></ErrorCode>
<Description></Description>
<OriginalXML></OriginalXML>
</ErrorMessage>
</Message>
</VPOS>
The exact xml bindings are defined in xsd schema.
https://ecommerce-test.cardlink.gr/vpos/xsd/VPOS41.xsd
Resource Information
| Business partner | VPOS Request Urls (Authorization) | MPI Request Urls (Authentication) |
| Cardlink/Cardlink One | https://ecommerce-test.cardlink.gr/vpos/xmlpayvpos | https://ecommerce-test.cardlink.gr/mdpaympi/MerchantServer |
| Nexi | https://alphaecommerce-test.cardlink.gr/vpos/xmlpayvpos | https://alphaecommerce-test.cardlink.gr/mdpaympi/MerchantServer |
| Worldline | https://eurocommerce-test.cardlink.gr/vpos/xmlpayvpos | https://eurocommerce-test.cardlink.gr/mdpaympi/MerchantServer |
Description of request and response message elements and fields and their usage:
| Field/request | Type | Description |
| Request | ||
| VPOS | element | XML root element |
| Message | element type Message | Message contents element |
| version | attribute, xsi:string | Message version default value “4.1” Required or 2.1 |
| messageId | attribute, xsi:ID | Message unique identifier (values in request and reply messages this must match, also used for lookup signature reference object when validating signature) (“M1234567”). Begin with letter. |
| lang | attribute, xsi:string(2) | Message attribute to specify context language (Optional). (ISO 639-1 language code en, fi, sv, el, etc..) |
| timeStamp | Attribute xsi:dateTime | Approximate time when message was created |
| Digest (v2.1 only) | element xsi:string | Required if version = 2.1. The digest of message element if used instead of password to be calculated Base64(SHA2-256((utf8bytes(canonicalize(Message))+utf8bytes(sharedSecret)) |
| Signature | element ds:SignatureType | Required if version = 4.1. The xml signature as defined https://www.w3.org/TR/xmldsig-core/ Canonicalization http://www.w3.org/TR/2001/REC-xml-c14n-20010315 SignatureMethod Algorithm http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 Digest Method Algorithm http://www.w3.org/2001/04/xmlenc#sha256Requests are signed by merchant private key and validated with merchant Certificate (merchant certificate generation is referred to section 5) |
| SaleRequest AuthorisationRequest CaptureRequest OriginalCreditRequest RefundRequest CancelRequest RecurringOperationRequest StatusRequest TokenizationRequest PaymentLinkRequest |
element | Request Message element depending on request type |
| Authentication | element | Authentication element of request Message |
| Mid | xsi:string (N1..30) | Merchant number/identification in VPOS |
| OrderInfo | Orderinfo element of request Message | |
| DeviceCategory | xsi:string (1) | Optional |
| OrderId | xsi:string AN1..50 | Merchant defined unique order id. Max length 45 for recurring payment. |
| OrderDesc | xsi:string AN1..128 | Order description defined by Merchant |
| OrderAmount | xsi:decimal (max 9+3 or 10+2) | Order amount (decimal number >0.0 and max 12 digits + decimal point). Amount is set to 0.0 for Tokenization without Authorization |
| Currency | xsi:string A3 | ISO4217 alphabetic currency code (EUR) |
| PayerEmail | xsi:string AN1..64 | Order payer email address (string..64) |
| PayerPhone | xsi:string N1..30 | Order payer phone number, optional but strongly recommended (string..30) |
| AddFraudScore | xsi:integer | Incoming starting risk score (integer) |
| BlockScore | xsi:integer | Optional block score parameter that will be used to block the transaction if transaction riskScore reaches this value or above. (Postive Integer number) |
| Elements Var1.Var9 Var1, Var2, Var3, Var4, Var5, Var6, Var7, Var8, Var9 |
xsi:string AN1..1024 | Free variable defined by merchant. |
| MOTO | xsi:integer N1 | Indicating whether it is a MOTO transaction (1 indicates MOTO) |
| Weight | xsi:decimal | Order shipping weight (kg) if item is shippable and shipping needs to be calculated by VPOS (decimal number >0) and it is supported |
| Dimensions | xsi:string AN1..25 | 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 |
| BillingAddress | element address | Element of OrderInfo |
| country | xsi:string AN2 | Billing address country code (string 2 ISO 3166-1-alpha-2 code (US, FI, GB)) For Kosovo, use Serbia’s country code RS |
| state | xsi:string AN1..50 | Billing address state (string 2 3166-2 country subdivision code). This value only applies to countries that have states (e.g USA) |
| zip | xsi:string AN1..16 | Billing address zip code (string..16) |
| city | xsi:string AN1..50 | Billing address city (string..50) |
| address | xsi:string AN1..50 | Billing address street (string..50) |
| ShippingAddress | element:address | Element of OrderInfo |
| country | xsi:string AN2 | Shipping address country code (string 2 ISO 3166-1-alpha-2 code (US, FI, GB)) Optional, required when parameter weight or dimensions are present. |
| state | xsi:string AN1..50 | Shipping address state (string..50) Optional, required when parameter weight or dimensions are present. |
| zip | xsi:string AN1..16 | Shipping address zip code (string..16) Optional, required when parameter weight or dimensions are present. Optional, required when parameter weight or dimensions are present. |
| city | xsi:string AN1..50 | Shipping address city (string..50) Optional, required when parameter weight or dimensions are present. |
| address | xsi:string AN1..50 | Shipping address street (string..50) Optional, required when parameter weight or dimensions are present. |
| PaymentInfo | Payment info element of request | |
| PayMethod | xsi:string AN1..20 | valid values: visa for VISA cards mastercard for MasterCard maestro for Maestro amex for American Express diners for Diners discover for Discover |
| CardPan | xsi:string N11..19 | Card number |
| CardExpDate | xsi:string N4 | Card expiration date in format YYMM |
| CardCvv2 | xsi:string N3..4 | CVV2/CVC2 security code from card. |
| CardHolderName | xsi:string AN1..24 | Card holder name |
| CardEncData | Xsi:string ..2048 | In case on merchant merchant site user browser RSA card data encryption is used this field contains encrypted card data in form of Base64(RSA(UTF8Bytes(“pn={pan}&ey={exp year}&em={exp month}&c2={cvv2}&cn={cardholdername}”)) Values are url encoded and with utf-8 char encoding (with javascript encodeURIComponent). This all is handled by server supplied component, merchant just need to forward value as returned to this field content. If this field is present then fields CardPan, CardExpDate, CardHolderName, CardCvv2 must not be sent |
| RecurringIndicator | xsi:string AN1 | Value “R” indicates recurring payment |
| RecurringParameters | element | Recurring parameters element |
| ExtRecurringfrequency | xsi:string N1..3 | A value indicating the number of days between the recurring payments. 28 is a special value indicating a month. |
| ExtRecurringenddate | xsi:string N8 | Recurring end date Format yyyymmdd |
| InstallmentParameters | element | Installments parameters element |
| ExtInstallmentoffset | xsi:integer N1..2 | Defines the number of months between the entering of the transaction, in case installment payment.
Currently, should have value 0. |
| ExtInstallmentperiod | xsi:integer N1..2 | Defines the number of monthly payments in case installment payment. Valid value must be >1 |
| ThreeDSecure | element | Element to support ThreeDSecure in XML api |
| EnrollmentStatus | xsi:string AN1 | In case of merchant is processing 3D secure prior to sending this xml message this field should contain 3D secure enrollment status (Y, N, U) |
| AuthenticationStatus | xsi:string AN1 | In case of merchant is processing 3D secure prior to sending this xml message this field should contain 3D secure authentication status (Y, N, U, A) |
| CAVV | elem xsi:string AN28 | In case of merchant is processing 3D secure prior to sending this xml message this field should contain 3D secure CAVV if authenticated. Base64 encoded value (28 chars) of CAVV of value of 20 bytes |
| XID | elem xsi:string AN28 | In case of merchant is processing 3D secure prior to sending this xml message this field should contain 3D secure XID if authenticated. base64 encoded 28 char value of 20 byte XID |
| ECI | elem xsi:string N2 | In case of merchant is processing 3D secure prior to sending this xml message this field can optionally contain ECI value |
| Protocol | elem xsi:string | Required if not 3DS1, value from MPI responses |
| Attribute | elem AttributeType 0..n counts | Extra attributes for 3DS2. Add all attributes with names TDS2.transStatus TDS2.transStatusReason TDS2.threeDSServerTransID TDS2.dsTransID TDS2.acsTransID TDS2.authenticationType TDS2.challengeCancel depending if available in MPI response.Attribute named TDS2.dsTransID is currently required if successful 3DS2 authentication, others currently recommended. |
| ExtXOrderId | xsi:string AN1..50 | Optional merchant and acquirer agreed extension for recognizing returning customers with submitting previous successful order id of the merchant recognized customer. If functionality is not enabled for merchant this parameter is silently ignored. And if in such case CardPan is missing or is not valid error condition will be generated. Also used in original credit to locate original payment. |
| ExtTokenOptions | Xsi:string N1 | Optional for merchant and acquirer agreed token extension. Value 1 if request tokenization and PAN is supplied. |
| ExtToken | Xsi:string N12..19 | Optional merchant and acquirer agreed token extension for recognizing payment tokens from previous successful payments. |
| TransactionInfo | element | Transaction info element (used in recurring cancel operation present in RecurringOperationRequest only) |
| OrderId | xsi:string AN1..50 | Merchant defined unique order id (of original payment). Max length 45 for recurring payment. |
| TxId | Xsi:long | TxId applicable in StatusRequest message only |
| Operation | xsi:string AN1..25 | Predefined String value, Currently supported operation: Cancel (to cancel recurring occurring) |
| TxType | element xsi:string | Required for PaymentLinkRequest possible values can be PAYMENT_PREAUTH or PAYMENT |
| LinkValidityDays | element xsi:int | Optional for PaymentLinkRequest payment validity in days |
| MailLinkIfValidMail | element xsi:boolean | Optional for PaymentLinkRequest to request payment link mail to be sent by server if payerMail in OrderInfo was present |
| Responses/ Notification | ||
| VPOS | element | XML root element |
| Message | element type Message | Message contents element |
| version | attribute, xsi:string | Message version default value “1.0” Required |
| messageId | attribute, xsi:ID | Message unique identifier (values in request and reply messages this must match, no other purpose) |
| lang | attribute, xsi:string (2) | Message attribute to specify context language (Optional) (ISO 639-1 language code en, fi, sv, el, etc..) |
| timeStamp | Attribute xsi:dateTime | Message timestamp when approximate time of when message was created. Example 2015-04-30T12:21:02.402+03:00 |
| Digest (v2.1 only) | element xsi:string | The digest of message element if used instead of password to be calculated Base64(SHA2-256((utf8bytes(canonicalize(Message))+utf8bytes(sharedSecret)) |
| Signature | element ds:SignatureType | The xml signature as defined https://www.w3.org/TR/xmldsig-core/ Canonicalization http://www.w3.org/TR/2001/REC-xml-c14n-20010315 SignatureMethod Algorithm http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 DigestMethodAlgorithm http://www.w3.org/2001/04/xmlenc#sha256 Responses are signed by processor private key and validated with Processor certificate (processor certificate is referred to Section 6. page 31) |
| Response | element | Element of response type and named as AuthorisationResponse, CaptureResponse, OriginalCreditResponse, RefundResponse, CancelResponse, RecurringOperationResponse |
| OrderId | xsi:string | Same value as in request message OnrderInfo. |
| OrderAmount | xsi:decimal | Same value as in request message OnrderInfo |
| Currency | xsi:string | Same value as in request message OnrderInfo |
| PaymentTotal | xsi:decimal | Actual payment amount normally equals orderAmount or orderAmount + any fees if applicable. |
| Status | xsi:string | Transaction status in response or notification messages AUTHORIZED, CAPTURED – payment was successful (accept order) REFUSED – payment failed, payment was denied for card or by bank (deny order) REFUSEDRISK – payment failed, payment was denied for card by risk score (deny order) CANCELED – only in recurring operation response if supsequent requrrings are set to be canceled ERROR – input, system or network error (deny order) |
| TxId | Xsi:long | Server supplied transaction id |
| Sequence | Xsi:integer | Used with recurring |
| PaymentRef | Xsi:string | Remote payment reference like issue approval code. |
| RiskScore | xsi:integer | Optional risk score calculated by risk scoring subsystem if available |
| ExtToken | Xsi:string | Optional payment token if tokenization was requested and performed |
| ExtTokenPanEnd | Xsi:string | Optional payment token related PAN ending 4 numbers |
| ExtTokenExp | Xsi:date | Optional payment token expiration. (YYYY-MM-DDZ) example 2018-02-01+02:00 |
| ErrorCode | Xsi:string | Error code |
| Description | Xsi:string | Error or result description text |
| PaymentLink | xsi:string element | Payment Link URL |
| LinkMailed | xsi:boolean element | Indicator if payment link mail was sent to mail server. |
| ReqcurringNotification | ||
| Authentication | element | Authentication element of request Message |
| Mid | xsi:string (N1..8) | Merchant number/identification in VPOS |
| OrderId | xsi:string | Same value as in request message OrderInfo |
| OrderAmount | xsi:decimal | Same value as in request message OrderInfo |
| Currency | xsi:string | Same value as in request message OrderInfo |
| PaymentTotal | xsi:decimal | Actual payment amount normally equals orderAmount or orderAmount + any fees if applicable. |
| Status | xsi:string | Transaction status in response or notification messages AUTHORIZED, CAPTURED – payment was successful (accept order) REFUSED – payment failed, payment was denied for card or by bank (deny order) CANCELED – only in recurring operation response if subsequent recurring are set to be canceled ERROR – input, system or network error (deny order) |
| TxId | Xsi:long | Server supplied transaction id of recurring master that started requiring sequence |
| Sequence | Xsi:integer | Recurring sequence number |
| SeqTxId | Xsi:long | The recurring sequence transaction server supplied id |
| PaymentRef | Xsi:string | Remote payment reference like issue approval code. |
| ErrorCode | Xsi:string | Error code |
| Description | Xsi:string | Error or result description text |
| Attribute | Complex element many |
|
| StatusRequest | Query for transaction status | |
| Authentication | element | Authentication element of request Message |
| Mid | xsi:string | Merchant number/identification in VPOS |
| TransactionInfo | element | |
| OrderId | Element Xsi:string | Use either order id or txid to query results if order id used then all transactions referenced are included such as captures, refunds associated |
| TxId | Element Xsi:long | Use txId to query by txId, only single transaction data is returned |
| StatusResponse | Response of transaction status containing one or many TransactionDetails | |
| TransactionDetails | element | One or many |
| OrderId | element | |
| OrderAmount | Element xs:decimal | Merchant submitted order amount |
| Currency | Element xs:string | Order currency |
| PaymentTotal | Element xs:decimal | Final payment amount (order +/- adjustments, fees etc) |
| Status | Element xs:string | Payment status |
| TxId | Element xs:long | Transaction identifier |
| Sequence | Element xs:integer | In case of recurring |
| PaymentRef | Element xs:string | Payment reference or approval code if available |
| RiskScore | Element xs:integer | Risk score if available |
| ErrorCode | Element xs:string | Not used |
| Description | Element xs:string | Status description |
| Attribute | Complex element many |
Many, rest of the transaction data. <Attribute name=”MERCHANT NO”>0000001</Attribute> <Attribute name=”USER IP”>195.222.10.3</Attribute> <Attribute name=”CHANNEL”>Redirection</Attribute> <Attribute name=”3D STATUS”>1 – Fully authenticated</Attribute> <Attribute name=”SETTLEMENT STATUS”>NA</Attribute> <Attribute name=”BATCH NO”>28</Attribute> <Attribute name=”ISO response code”>15</Attribute> <Attribute name=”ORDER DESCRIPTION” /> <Attribute name=”CARD MASK PAN”>4016#####0002</Attribute> <Attribute name=”ECOM-FLG”>5</Attribute> <Attribute name=”ECI”>05</Attribute> <Attribute name=”PAYEREMAIL”>demo@cardlink.gr</Attribute> <Attribute name=”PAYERPHONE”>+372 123 1234</Attribute> <Attribute name=”BILLCOUNTRY”>FI</Attribute> <Attribute name=”BILLZIP”>76543</Attribute> <Attribute name=”BILLADDRESS”>Billto tn 6-9</Attribute> <Attribute name=”SHIPCOUNTRY”>FI</Attribute> <Attribute name=”SHIPSTATE”>Harjumaa</Attribute> <Attribute name=”SHIPZIP”>12345</Attribute> <Attribute name=”SHIPADDRESS”>Viru tn 6-9</Attribute> <Attribute name=”EXTACQUIRERID”>026</Attribute> |
| TxType | Element xs:string | Transaction type |
| TxDate | Element xs:dateTime | Transaction execution timestamp |
| TxStarted | Element xs:dateTime | Transaction started timestamp |
| TxCompleted | Element xs:dateTime | Transaction completed timestamp |
| PaymentMethod | Element xs:string | Payment method used. |
| ErrorMessage | element | Response type of ErrorMessage, normally given if request message validation failed or system error. |
| ErrorCode | Xsi:string | Error code |
| Description | Xsi:string | Error description text |
| OriginalXML | Xsi:string | Encoded original XML received in case the error was in XML parsed |
| Field element/Request | Sale/AuthorizationRequest | TokenizationRequest | CaptureRequest | OriginalCreditRequest | RefundRequest | CancelRequest | RecurringOperationRequest | SaleResponse | AuthorizationResponse | CaptureResponse | OriginalCreditResponse | RefundResponse | CancelResponse | RecurringOperationResponse | RecurringNotification | PaymentLinkRequest | PaymentLinkResponse | Description |
| Message | ||||||||||||||||||
| version | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | 4.1 or 2.1 |
| messageId | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | Unique value of numbers and or chars xsi:ID and matching in request, response messages, max length 128. Begin with letter. |
| lang | O | O | O | O | O | O | O | O | O | O | O | O | O | O | O | O | O | Optional iso language code as el, en, ru, fi, et, sv. This is used to set context language in case emails or any other type actions are triggered with this request. |
| timeStamp | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | Required |
| Authentication | ||||||||||||||||||
| Mid | R | R | R | R | R | R | R | R | ||||||||||
| OrderInfo | R | R | R | R | R | R | ||||||||||||
| DeviceCategory | ||||||||||||||||||
| OrderId | R | R | R | R | R | R | ||||||||||||
| OrderDesc | O | O | O | |||||||||||||||
| OrderAmount | R | R | R | R | R | R | ||||||||||||
| Currency | R | R | R | R | R | R | ||||||||||||
| PayerEmail | O | R | ||||||||||||||||
| PayerPhone | O | O | ||||||||||||||||
| AddFraudScore | O | O | ||||||||||||||||
| BlockScore | O | O | ||||||||||||||||
| Var1 | O | O | O | |||||||||||||||
| Var2 | O | O | O | |||||||||||||||
| Var3 | O | O | O | |||||||||||||||
| Var4 | O | O | O | |||||||||||||||
| Var5 | O | O | O | |||||||||||||||
| Var6 | O | O | O | |||||||||||||||
| Var7 | O | O | O | |||||||||||||||
| Var8 | O | O | O | |||||||||||||||
| Var9 | O | O | O | |||||||||||||||
| MOTO | O | O | ||||||||||||||||
| Weight | O | O | ||||||||||||||||
| Dimensions | O | O | ||||||||||||||||
| BillingAddress | O | R | Billing address element and sub elements | |||||||||||||||
| ShippingAddress | O | C | Shipping address element and sub element. Required in case of shipping of goods. | |||||||||||||||
| PaymentInfo | R | O1 | O1 | O1 | O | |||||||||||||
| PayMethod | R3 | O1 | O1 | O1 | – | |||||||||||||
| CardPan | R2 | O1 | O1 | O1 | – | Not present if CardEncData present | ||||||||||||
| CardExpDate | R | – | Not present if CardEncData present | |||||||||||||||
| CardCvv2 | O | – | Required if not MOTO and required for card type brand. Not present if CardEncData present. | |||||||||||||||
| CardHolderName | C | – | Optional but highly recommended. Not present if CardEncData present. | |||||||||||||||
| CardEncData | C | – | Used if RSA card encryption then CardPan, CardExpDate, CardHolder Name and CardCcc2 shall not be present | |||||||||||||||
| RecurringIndicator | C | – | Required for recurring payment | |||||||||||||||
| RecurringParameters | C | Required for recurring payment | ||||||||||||||||
| ExtRecurringfrequency | C | Required for recurring payment | ||||||||||||||||
| ExtRecurringenddate | C | Required for recurring payment | ||||||||||||||||
| InstallmentParameters | C | Required for installment payment | ||||||||||||||||
| ExtInstallmentoffset | C | Required for installment payment | ||||||||||||||||
| ExtInstallmentperiod | C | Required for installment payment | ||||||||||||||||
| ThreeDSecure | C | Required for 3D transactions | ||||||||||||||||
| EnrollmentStatus | C | Required for 3D transactions | ||||||||||||||||
| AuthenticationStatus | C | Required for 3D transactions | ||||||||||||||||
| CAVV | C | Required for 3D transactions | ||||||||||||||||
| XID | C | Required for 3D transactions | ||||||||||||||||
| ECI | C | Required for 3D transactions | ||||||||||||||||
| Protocol | C | Required for 3DSv2 transactions | ||||||||||||||||
| Attribute | C | TDS2.dsTransID attribute is required for 3DSv2 transactions | ||||||||||||||||
| ExtXOrderId | O2 | R | O2 – may be present instead of CardPan. Required for original credit to lookup source payment. | |||||||||||||||
| ExtTokenOptions | O | |||||||||||||||||
| ExtToken | O | |||||||||||||||||
| TransactionInfo | R | |||||||||||||||||
| OrderId | R | |||||||||||||||||
| Operation | R | |||||||||||||||||
| Signature | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | Required for all (v4.1) |
| Digest | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | Required for all (v2.1) |
| Card | R | CardInfo | ||||||||||||||||
| Token | TokenInfo | |||||||||||||||||
| TxType | R | for PaymentLInk PAYMENT_PREAUTH, PAYMENT | ||||||||||||||||
| LinkValidityDays | O | Optional days payment link is valid, defaults to merchant or system value | ||||||||||||||||
| MailLinkIfValidMail | O | xsi:boolean true/false indicates if service will email link to payer if payeremail in OrderInfo | ||||||||||||||||
| Responses/Notification | ||||||||||||||||||
| OderId | R | R | R | R | R | R | R | R | R | Order Id supplied by merchant originally | ||||||||
| OrderAmount | R | R | R | R | R | R | R | R | ||||||||||
| PaymentTotal | R | R | R | R | R | R | R | R | ||||||||||
| Currency | R | R | R | R | R | R | R | R | ||||||||||
| Status | R | R | R | R | R | R | R | R | R | Status | ||||||||
| TxId | C | C | C | C | C | C | R | R | In case of transaction processing has started (no rejection due invalid input request), In case of recurring Notification this is master recurring transaction id | |||||||||
| Sequence | R | Sequence of recurring in notification. | ||||||||||||||||
| SeqTxId | R | The executed recurring sequence transaction id | ||||||||||||||||
| PaymentRef | C | C | C | C | C | C | C | Payment reference such as approval code if available | ||||||||||
| RiskScore | O | O | Optional risk score calculated by risk scoring subsystem if available | |||||||||||||||
| ExtToken | O | O | ||||||||||||||||
| ExtTokenPanEnd | O | O | ||||||||||||||||
| ExtTokenExp | O | O | ||||||||||||||||
| ErrorCode | C | C | C | C | C | C | C | C | C | Error code in case of Status=ERROR | ||||||||
| Description | O | O | O | O | O | O | O | O | O | Optional error description | ||||||||
| Attribute | O | O | O | O | O | O | O | O | O | Optional attributes, may be custom per implementation. | ||||||||
| OriginalXML | In general error message only to copy back the error as content received for merchant debugging. | |||||||||||||||||
| PaymentLink | R | present if no error | ||||||||||||||||
| LinkMailed | R | present if no error | ||||||||||||||||
| Signature | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | Required for all (v4.1) |
| Digest | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | R | Required for all (v2.1) |
Download table here
O1 - if supported feature then fields may not need to be present if not supported then the fields are required. Availability of this option shall confirm with system administrator (Your customer support). If values not sent, then whole PaymentInfo element shall be excluded from message.
R2 and O2 - If system supports and merchant is set tp participate in returning customer recognition extension then if merchant already has a successful order with a card with this customer and the card is still valid and customer chooses to make this next order with same card and the days and amounts between orders are in certain limits then merchant may send ExtXOrderId instead of CardPan. In such case if validations are passed system automatically uses pan from previous specified order. Recommended maximum period between previous order and next returning customer extension order could be 6 months (180 days).
| Field element/requests | StatusRequest | TokenizationRequest | StatusResponse | TokenizationResponse | Description |
| StausRequest | |||||
| Authentication | |||||
| Mid | R | R | |||
| TransactionInfo | R | ||||
| OrderId | C | Either OrderId or TxId is required | |||
| TxId | C | Either OrderId or TxId is required | |||
| StatusResponse | R | ||||
| TransactionDetails | R | ||||
| OrderId | R | ||||
| OrderAmount | R | ||||
| Currency | R | ||||
| PaymentTotal | R | ||||
| Status | R | ||||
| TxId | R | ||||
| Sequence | O | ||||
| PaymentRef | O | ||||
| RiskScore | O | ||||
| Description | O | ||||
| Attribute | O | List of attributes depending on what information is available. | |||
| Attribute name can be one of the following: | |||||
| MERCHANT NO – merchant number | |||||
| REFUNDED AMOUNT – amount refunded if available | |||||
| USER IP – user IP if available | |||||
| CHANNEL – channel originated | |||||
| 3D STATUS – status | |||||
| CAPTURED AMOUNT – captured amount | |||||
| SETTLEMENT FILE – settlement file name | |||||
| BATCH NO – batch number | |||||
| ISO response code – iso response if available | |||||
| ExtData – additional data from external payment systems if available | |||||
| ORDER DESCRIPTION – order description | |||||
| CARD MASK PAN – masked pan 5+3 or 4+4 or 6+2 | |||||
| INSTALLMENT SEQUENCE | |||||
| INSTALLMENT PERIOD | |||||
| INSTALLMENT OFFSET | |||||
| RECURRING SEQUENCE | |||||
| RECURRING END DAT | |||||
| RECURRING FREQUENCY | |||||
| ECOM-FLG – ecom flag in authorization message | |||||
| ECI – eci from mpi | |||||
| VAR1..VAR9 | |||||
| PAYEREMAIL | |||||
| PAYERPHONE | |||||
| BILLCOUNTRY | |||||
| BILLSTATE | |||||
| BILLZIP | |||||
| BILLADDRESS | |||||
| SHIPCOUNTRY | |||||
| CancelRequest | |||||
| RecurringOperationRequest | |||||
| StatusRequest | |||||
| TokenizationRequest | |||||
| SHIPSTATE | |||||
| SHIPZIP | |||||
| SHIPADDRESS | |||||
| BONUS PARTICIPATION* | |||||
| BONUS REF* | |||||
| BONUS ADJUSTMENT* | |||||
| BONUS STATUS* | |||||
| BONUS DETAILS* | |||||
| RETURNING USED** | |||||
| RETURNING ORDER ID** | |||||
| *-Only possible if with special bonus loyalty extension. | |||||
| **-Only possible if with returning customer extension. | |||||
| TxType | R | ||||
| TxDate | R | Transaction exec date | |||
| TxStarted | R | Transaction started | |||
| TxCompleted | O | May be missing if transaction did not complete due errors. | |||
| PaymentMethod | O | ||||
| Card | R | R | CardInfo type ref required. If CSE, then encData required, else pan, expiration date required | ||
| Attribute:ref | R | R | unique number request id within merchant scope | ||
| Attribute:pan | C | Card pan (required if plain, no encData) | |||
| Attribute:exp | C | Card expiry date (required if plain, no encData, xsd:date (YYYY-MM-DD)) | |||
| Attribute:chn | C | Cardholder name (required if plain, no encData) | |||
| Attribute:encData | C | CSE (required if encoded card data) | |||
| Attribute:status | R | Status of tokenization (OK if no errors occurred) | |||
| Attribute:tokenValue | O | Value of token | |||
| Attribute:panEnd | O | Last 4 digits of pan | |||
| Attribute:exp | O | Expiration Date | |||
| id | R | R | R | id attribute of request/response matching | |
| status | R | ACCEPTED, PENDING, SUCCESS, ERROR | |||
| statusMessage | O | Optional status description | |||
| Token | R | Token Information element (one or more) included in TokenizationResponse |
Currently supported operations:
AuthorisationRequest-make a pre-authorization
CaptureRequest- capture a pre-authorization
RefundRequest- make refund
SaleRequest- make a payment
CancelRequest- make reversal for an unsettled transaction
RecurringOperationRequest- with operation Cancel, cancel recurring master scheduling
RecurringNotification – Optional message posted to merchant if a recurring child is executed on server, merchant does not need to send response XML to this on accept merchant server should respond with http status code 200/OK or in case merchant does not recognize the transaction 406/Not Acceptable or 400/Bad Request if the message format is invalid. Server just acknowledges the response code and performs no additional actions based on merchant response code.
StatusRequest- query transaction status
TokenizationRequest- tokenize a card to token
PaymentLinkRequest- Generate a one time payment link
Error code values:
Filled in case status is ERROR with following values
M1 – Invalid merchant id
M2 – Authentication failed (wrong password or digest or signature)
SE – System error (message contains error id, system or configuration error to be investigated)
XE – Invalid XML request not parseable or does not validate
I0 – Invalid or unsupported request
I1 – Message contains invalid data item or missing required item
I2 – Message contains invalid installment parameters
I3 – Message contains invalid recurring parameters
I4 – Message contains invalid or mismatching card data
I5 – Message contains invalid expiration date card data
I6 – Selected payment method does is not supported or not matching the payment card
O1 – Operation is not allowed because logic is violated or wrong amounts
O2 – Original transaction is not found to perform operation.
May be also filled in case of status is REFUSED with acquirer network supplied ISO response code
Digest calculation with XML API: 2.1 https://developer.cardlink.gr/documentation_categories/integration/#Digest-calculation-with-XML-API-2.1
Signature calculation with XML API V4.1: https://developer.cardlink.gr/documentation_categories/integration/#Signature-calculation-with-XML-API-V4.1
Examples how to generate merchant keys
With openssl
It’s just possible to do all in one line:
openssl req -x509 -newkey rsa:2048 -sha256 -keyout merchantkey.pem -out merchantcert.pem -days 1460 -subj “/C=EE/ST=My State/L=my City/O=Company Name/OU=7711223/CN=www.mysite.com”
The output file merchantcert.pem need to be sent to service provider to install with Your merchant account so Your messages will be validated with public key in Your certificate.
C – is two letter country code
L – locality eg. city where you are located.
OU – is recommended to fill with Your merchant number with service provider.
O – shall be your company full or public name.
CN – is recommended (not required as with server certificates) to be your website name
rsa:keysize is recommended to be 2048 or 3072 bits for foreseeable future and validity days up to 1460 days (4 years), ask service provider if it has specific policy or requirements.
Use necessary measures to protect your private key in generated file merchantkey.pem.
Converting private key to PKCS8 format handleable by java:
openssl pkcs8 -topk8 -in merchantkey.pem -inform PEM -outform PEM -out merchantkey-p8.pem -nocrypt
With java keytool
With java keytool private key remains in keystore and cannot be extracted unless special software is used. So Your software shall operate directly with this keystore then.
keytool -genkey -keyalg RSA -sigalg SHA256withRSA -dname ”CN=www.mysite.com,OU=7711223,O=Company Name,L=my City,S=My State,C=EE” -keysize 2048 -validity 1460 -alias mykey2017 -storetype JCEKS -keystore mykeystore.jceks -keypass strongPassKey -keystore mycerts.jceks -storepass strongPass
Now export Your certificate to a file that can be sent to service provider:
keytool -exportcert -alias mykey2017 -file merchantcert.pem.cer -storetype JCEKS -keystore mycerts.jceks -storepass strongPass -rfc
Processor Certificate
Processor certificate is used by merchant to calculate the signature value for the response messages.
For testing purposes, merchant can use the following processor certificate:
—–BEGIN CERTIFICATE—– MIIEVTCCAr0CBGQm1T4wDQYJKoZIhvcNAQELBQAwbzEfMB0GA1UEAxMWQ2FyZGxpbmtNZXNzYWdl U2lnbmluZzELMAkGA1UECxMCUFMxEDAOBgNVBAoTB1ByaW50ZWMxDzANBgNVBAcTBkF0aGVuczEP MA0GA1UECBMGQXR0aWtpMQswCQYDVQQGEwJHUjAeFw0yMzAzMzExMjQyMzhaFw0zMzAzMjgyMDU5 NTlaMG8xHzAdBgNVBAMTFkNhcmRsaW5rTWVzc2FnZVNpZ25pbmcxCzAJBgNVBAsTAlBTMRAwDgYD VQQKEwdQcmludGVjMQ8wDQYDVQQHEwZBdGhlbnMxDzANBgNVBAgTBkF0dGlraTELMAkGA1UEBhMC R1IwggGiMA0GCSqGSIb3DQEBAQUAA4IBjwAwggGKAoIBgQCEI77PnF3W9npHsYFebQVEDbkoI7FY 0ZHvHtXKcwciGrXkhD6aoAGagER5cZjkeaTqdeS8yyML5ASYiXKmDNIJKTdWWwz/qiFixA5VRkwB JNWiXuDySLvcPUvn9TzmrGITd00kZIGe7J9f0dZGzzkNWDY5sqAPCRhEEZWMyEYBLIJp7I2oFyo7 38WTDOMua3V+hghqzFo6z2S97vjCGtCN2Wn4lG3WyDyoiXudFRTt2FbXMgpr/AIt/YXHWs3vOj7n Q0mfSmuLFy2X25gZcKfCo2jocH9IFozd3YIys+KIWh7uv3qLpbLEIpQ2SQ+gt57JK7A1Lw2luuOq 6qPlK1RV2AW4W9L0g7jJc6t4hM5NMZJYzgYum/ajcoCTl+ip/UpIRDJRL+w5cbZ/Lhc4+qcgTi1p liJRWvEoRUD0Bi9x/ACYEVj5QeZgvollo4zl+3lrrZaYfLEnIp8vet1RFTri6I5CRjokubbcyBxz d9+FTdW2Co66Ql7hPSv5UPO35ZcCAwEAATANBgkqhkiG9w0BAQsFAAOCAYEANcFACfhM7FhNYJaO XVwHdaE3fp2hMLajIg2LXhgjpjd3rM9nibhCbKBEIPNg8xWMPXbUdTcSqVKudjyuKxvdTkx6fMEg iLsaC29+JDfM1oXiGXiLiT11ayw8r94OX3AzXf8CYXLfXlY1AkuNXsp2Ocbn+/kFb3+9YG10qWzf qU3p7BN0chHDXaK+x3JfNg+z+8URt62w0e9+jDRfr2V/8Z7ev2aO2X/LZmCG9peYaELsSAgqvLFq SOOOXZtG7h7hqcE3xCSRlH13hK1gMtMQRRtiwbr2sQUL5YECpWWK1S+kyfcawQDiA5qxIcxpTqPz L7gPX4dzV/nQl40Jk+D0bTOaKoCMW1or5BRRo5mt4Uc+8ChHKQzr20VUmwCVf2FUODGCh4gg3DYH uU46fkKXexUD92aI/d/F/Vv/LZORZ8Wt4eIEmpmWW08Xww7LEqDpzHyGZ5BNuHf6r5Yb1rmS1Z/L PRu+VcI4Hy8081eP5rAcvjUTCjp6A9EwbDKsjH5K
—–END CERTIFICATE—–
For production, please contact via email at ecommerce_support@cardlink.gr