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>
</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

Description of request and response message elements and fields and their usage: 

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).

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. With operation RecurringChild to execute recurring taking payment info from valid captured recurring master

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

1. Introduction

Modirum has developed a range of software products to support the use of 3-D Secure protocol for payer
authentication. Modirum MPI is a product that is developed for merchants, acquirers or payment service
providers that want to implement the 3-D Secure Merchant Plug-In (MPI) protocol. Modirum MPI is
compliant with Visa, MasterCard, American Express, Diners and JCB schemas (protocol version 1.0.2).
Since version 4.0.2.51 also ThreeDSecure 2.0 and 2.1 support has been established. As of now 2.0 is
discontinued and Modirum MPI is certified to 2.1 protocol.
This document is the reference manual of Modirum MPI merchant interface. It has been targeted to
merchants who connect to and process 3D Secure through Modirum MPI
The structure of this document is as follows:

• Section HTTP POST Interface describes the merchant application interface of the product. The
  interface enables implementation of 3-D Secure protocol without any programming work. This
  section includes a separate summary of different result values of the 3-D Secure process
  (mdStatus, eci).

The new interface specification introduces recently emerged new MPI extension such as Brazil Market
and Trusted Third Party and ThreeDSecure 2.x specifics and extensions. Please check for new fields in
this version to ensure compability (look for “Since 4.0.2.54”)

1.1 Prerequisites

It is assumed that the reader has basic knowledge of payment cards in the traditional commerce and in
electronic commerce. It is also assumed that the reader has basic knowledge about the acquiring process
of the payment cards.

1.2 Glossary

This section includes selected terms that are commonly used in the document. An extensive 3-D Secure
glossary is available in 3-D Secure: System Overview, available through the “Vendors & Merchants” link
on http://corporate.visa.com.

1.3 Getting Started

The purpose of this section is to describe the basic functionality of Modirum MPI. Functions of the product
are walked- through with help of examples. More detailed description of the product is included in the rest
of the document.
Note that the examples can be tested with a demo merchant and a live Modirum MPI. In order to get access
to Modirum demo site, please contact Modirum support.
In order to try the following examples with Modirum software, please note the following
recommendations:

• With the example merchant application, it is recommended to use FireFox, Chrome, or Internet Explorer 9
  (or newer). The software has also been tested with other browsers, but there have been some technical
  problems with earlier browser versions.
• It is highly recommended to use a display with a minimum 1024×786 graphics resolution.

1.4 Which MPI Interface Should Be Used

Modirum MPI supports several alternative protocols for integration to the payment page:
1. HTTP POST as Foreground
2. HTTP XML or XML+SOAP API
Which one to use depends on how much integration effort you are willing to invest. The biggest architectural decision
you need to make is whether you will be using the MPI in “foreground” or “background” mode.
In “foreground” mode, the MPI is exposed directly to the Internet as a separate web application, typically on a separate
dedicated server or a separate web application on some server also used for other purposes.
In “XML” mode, the MPI may not be directly exposed to Internet for end users but only for inbound directory
connection for 3DS2 RReq, but some other application, typically the one displaying the payment page, handles the
user browser session and passes data between the cardholder browser and the MPI.
HTTP POST as foreground is the easiest and the technical integration effort should be up to few days, whereas XML
integration effort may be a few weeks.

1.4.1 HTTP POST as Foreground

Payment page and MPI are separate applications residing on same or different servers. In this model the transaction
flow is:
1 The payment page places MPI input values into HTTP fields on HTML page and redirects the user browser
to the MPI (using html form with Javascript).
2 MPI contacts directory and either returns immediately (not enrolled of frictionless authentication) or
redirects the user browser session to the ACS for challenge authentication.
3 ACS authenticates
4 MPI receives the user session back from the ACS.
5 MPI verifies the ACS response and Directory Response in 3DS2.
6 The MPI redirects the user browser back to the payment page and payment page application reads the
return values from HTML fields.

1.4.2 XML API or with SOAP

Payment page and MPI are separate applications residing on same or different servers. In this model, MPI never
receives the user browser session. The payment page application has the user session, performs necessary redirections
and receives the response.
In this model the transaction flow is:
1. The payment page places MPI input values into XML message and sends a background system-to-system
HTTP(S) call to the MPI.
2. MPI contacts directory and returns either final response, continue with enrollment and perform 3ds method
or finalized HML redirect form with included formatted PAReq/CReq message and ACS URL to the payment
page application.
3. If cardholder was enrolled and or challenge authentication requested, payment page application redirects the
user browser to the ACS with posting the PAReq/CReq from acquired from MPI.
4. ACS authenticates
5. Payment page application receives the user session back from the ACS with PARes/CRes.
6. Payment page application submits the ACS response PARes/CRes to the MPI in XML message for
verification.
7. MPI verifies the ACS response and DS direct response in case of 3DS2.
8. The MPI places results to merchant with final XML message with verified results and payment page
application reads the return values from XML message fields.
Note: The communications in background use XML or XML SOAP messages defined in interface specification
sections in this document.
So, the payment application should be aware of this and should be capable to send such requests to mpi and extract
the needed values from response XML/XML SOAP.

2 HTTP POST Interface

The simplest way to add 3-D Secure support to existing Merchant site is to use HTTP Post interface of the Modirum
MPI.
The control flow using HTTP Post interface is the following:
1. Merchant payment page asks the user all the relevant payment data, such as card number, expiry, etc.
2. Merchant payment page calculates the signature (v 4.0, detailed below) of all the fields to be posted to
Modirum MPI and POSTs these fields to the Modirum MPI.
3. Modirum MPI checks the card participation from the 3-D Secure directory and return the redirection
page to the Issuer ACS. The right directory is found with either card scheme id or matching the beginning
of the card number.
4. After the ACS is finished with the user authentication, ACS returns the control to the Modirum MPI. The
MPI Server verifies the signature of ACS and POSTs the response to either success URL or fail URL,
which the MPI has earlier passed to the ACS.
5. Merchant payment page reads the response and continues with the authorization of the payment (or does
the error processing).

2.1 Parameters of the Post to MPI Server

2.1.1 Start or process an authentication session

The following table describes the parameters of the POST from the payment page to Modirum MPI.
HTTP POST interface version has been upgraded to 4.0.

2.2 Calculation of the Signature

The digest in the incoming POST and in the return POST is calculated by the following rule.
1. Concatenate all the values of all the possible fields with semicolon “;” in between (including trailing
semicolon after the last value) as listed and in same order as in the table. If a parameter is missing
(not sent) or sent value is empty string “”, then value and separator is not concatenated.
2. Calculate RSA with SHA2-256 signature of step 1 (using of UTF-8 char encoding when converting
string to bytes) using your private key.
3. Return the signature in base64 encoded form.
Notes: Never implement the signature calculation in the browser using JavaScript or similar as this way you expose
your private key to the world. Only implement it on server side executed code as (jsp/servlet/asp/php etc.).
For example:
Signature=base64(RSA with SHA2-256( utf8bytes(value1;value2;…;value n;) ) )

java.security.PrivateKey privateKey = getPrivateKey(); //fetch your private key
java.security.Signature signature = Signature.getInstance("SHA256withRSA");
signature.initSign(privateKey);
signature.update(concatenatedValues.toString().getBytes(StandardCharsets.UTF_8));
byte[] sigBytes=signature.sign();
String sigStr=Base64.encode(sigBytes);

https://docs.microsoft.com/en-us/dotnet/api/system.security.cryptography.rsacryptoserviceprovider.signdata?
view=netframework-4.7.2
See also sigexample.cs
public static string sign(string valueToSign, String privateKey)
{
byte[] keybytes= parseKey(privateKey);
byte[] toSign = System.Text.Encoding.UTF8.GetBytes(valueToSign);
RSACryptoServiceProvider RSAalg = DecodePrivateKeyInfo(keybytes);
byte[] signature=RSAalg.SignData(toSign, "SHA256"); //RSAwithSHA256
string sigStr= Convert.ToBase64String(signature);
return sigStr;
}

Note: easiest ways to generate your merchant private key and self-signed certificate are:

a) Java keytool:
keytool -genkeypair -keyalg RSA -sigalg SHA256withRSA -alias merchant -keystore merchant.p12 –
storepass mypassword -validity 1440 -keysize 2048
keytool -export -alias merchant -keystore merchant.p12 -rfc -file merchant_x509.cer

b) openssl:
openssl req -sha256 -newkey rsa:2048 -nodes -keyout merchant.pem -x509 -days 1440 -out merchant_x509o.cer

2.3 Redirection to ACS

The MPI Server generates a redirection page, which includes a form that is posted to the ACS. The format of this
page depends on the channel. PAReq redirection-default templates of different channels are defined in WEBINF/templates xsl files.

2.4 Returning from MPI Server to Merchant Site

The standard method for returning control back from the MPI Server to the merchant is a redirection through the user
browser.
The standard control flow after receiving the PARes (or CPRS with condensed messages) is:
1. ACS Posts the PARes back to MPI Server via the user browser using the redirection.
2. MPI Server determines the status of the transaction and posts the status values to merchant payment page via
the user browser using the redirection.
3. Merchant server continues with authorization and after the authorization displays the confirmation page to
the user.

2.5 Parameters of return POST from MPI Server

The following table describes the parameters of the POST to okURL or failURL by Modirum MPI.

Note: In case of deviceCategory = 5 then no html is returned but name value pairs content only in application/xwww- form-urlencoded format. Response to service query also returns this set of parameters in application/x-wwwform-urlencoded format.

2.6 Modirum MPI Transaction mdStatus

mdStatus and eci fields
Modirum MPI returns many fields in the HTTP POST return interface, but there are two fields that have the most
significance from business transaction management point of view.

• mdStatus field provides all the information that is needed to determine, how to manage the transaction in
the merchant system:
➢ 0 = Not Authenticated, do not continue transaction
➢ 1 = Fully Authenticated, continue transaction
➢ 2 = Not enrolled (3DS1 only, may continue to transaction)
➢ 3 = Not enrolled cache (not used, was used in early 3DS1)
➢ 4 = Attempt (Proof of authentication attempt, may continue to transaction)
➢ 5 = U-received (grey area, continue to transaction depends schema rules)
➢ 6 = Error received (from Directory or ACS)
➢ 8 = Block by Fraud Score (used only if set up with FSS and scores configured)
➢ 9 = Pending (this code is not sent in red, internal, status only, except XML API or SDK in challenge)
➢ 50 = Execute 3DS method and continue to authentication (XML API or SOAP only
in return EnrollmentRequest(initial)).
➢ 51 = No 3DS method and continue to authentication (XML API or SOAP only in
return).
➢ 60 = Action completed, not sent only used internally for PReq result updates.
➢ 80 = Skip device case (no 3DS performed as device known not well capable)
➢ 81 = Skip challenge because requestor challenge ind (02 = No challenge requested)
➢ 88 = Skip 3DS because low risk (used only if with FSS and scores configured)
➢ 91 = Network error
➢ 92 = Directory error (read timeout)
➢ 93 = Configuration error
➢ 94 = Merchant input errors (also if merchant posted CRes not matching current tx state by RReq)
➢ 95 = No directory found for PAN/cardtype
➢ 96 = No version 2 directory found for PAN/cardtype
➢ 97 = If transaction not found on continue or service query
➢ 99 = System error (mpi unexpected error)
• eci field is relevant in Visa infrastructure, because there are certain business rules of how to fill the field into
the authorization messages. However, in Modirum MPI, eci field is filled only if the field is provided from
the ACS in the PARes message (as specified in the protocol spec). The value should then be passed to the
Visa authorization infrastructure as such.

Note the following recommendations:
– Firstly, check mdStatus to determine the final status of the transaction.
– The protocol specification requires passing the eci field as such to the authorization infrastructure if it is provided
in the PARes message (2.x ARes or PReq). Modirum MPI has value in eci field only if it has been provided in the
PARes message (2.x ARes or PReq).
Based on the current understanding of the Visa infrastructure business rules (note that this information is not
necessarily accurate and needs to be checked with Visa), the following eci values are recommended to be used in
authorization infrastructure:
• 6 = Non-participation and attempts (issuer liability).
• 9x = Service unavailable or system errors (merchant liability).
• No value, if authentication or signature check fails

Fully Authenticated Transactions
In fully authenticated transactions, the issuer and cardholder are participating in the 3-D Secure protocol, cardholder
authentication has been successful and signature has been validated.
Scenarios:
• Valid PARes or CPRS message has been received with status Y and the signature has been validated
successfully. Or in 2.x ARes or PReq has transStatus Y.
Values:
• mdStatus = 1
• MPI ECI is copied as such from the PARes or 2.x ARes or PReq (often 05 for Visa and 01 for MasterCard).
• Visa authorization ECI value 5 (note that this must be verified from Visa).

Non-participation and Not Enrolled Transactions
In the case, where the card issuer or cardholder is not participating to the 3-D Secure, the transaction can still be
completed. Business rules of this case depend on the card scheme. Also, the MPI may determine the non-participation
based on the card range missing from the cache.
Scenarios:
• VERes message has been received with status N (there is no difference with the issuer not participating
compared with the cardholder not participating).
• MPI uses cache and cannot find the card range in the cache.
Values:
• mdStatus = 2 if card not participating, or mdStatus = 3 if range not in cache.
• MPI ECI is empty.
• Visa authorization ECI value 6 (note that this must be verified from Visa).

Attempts
In 3-D Secure version 1.0.2, an attempt functionality was introduced. ACS implementations may produce signed
attempt-messages even in the cases where the issuer or cardholder is not participating.
Scenarios:
• ACS has produced PARes with A status and signature validation has been successful (can be issuer specific
ACS or centralized attempt-server). In 2.x in case ARes or PReq transStatus is A.
Values:
• mdStatus = 4
• MPI ECI is copied as such from the PARes

Authentication Errors
If authentication is not successful, the transaction should not be continued in those cases where the failure is fatal.
Scenarios:
• ACS has provided PARes with status N (e.g too many false passwords or signature check has failed)
• PARes signature validation has failed.
• In case of 2.x ARes or PReq transStatus is N, R
Values:
• mdStatus = 0
• MPI ECI is empty.
• Visa authorization ECI value is not relevant, because transaction cannot be continued (note that this must be
verified from Visa).

Authentication Unavailable
In some cases, the authentication may not be available. The unavailable status may come from the directory server or
ACS or it may be related to some data communication problems.
Scenarios:
• Directory server produces VERes message with U status or 2.x ARes or PReq transStatus is U.
• Directory server produces VERes or ACS PARes message with U status (e.g mobile protocol not supported).
• No connection to the directory server.
Values:
• mdStatus = 5
• MPI ECI is empty.
• Visa authorization ECI value 7 (note that this must be verified from Visa).

3-D Secure Errors
3-D Secure related error situations are managed separately.
Scenarios:
• Invalid input field in 3-D Secure message generation
• Merchant authentication in directory server fails
• Error message received from DS or ACS
Values:
• mdStatus = 6
• MPI ECI is empty
• Visa authorization ECI value 7 (note that this must be verified from Visa)

Merchant data errors
If merchant request was invalid or incomplete then:
Values:
• mdStatus = 94
• MPI ECI is empty
• Visa authorization ECI value 7 (note that this must be verified from Visa)

System, networks or directory errors
Sometimes Modirum MPI may produce some error messages related to MPI internal errors.
Scenarios:
• File system full or system misconfigurations.
• Database connection lost.
• Directory connection fails or response times out.
Values:
• mdStatus = 99, mdStatus = 92 or mdStatus = 93
• MPI ECI is empty
• Visa authorization ECI value 7 (note that this must be verified from Visa)

Fraud Score Block
If Modirum MPI is configured to use a fraud scoring service, the score is calculated prior to attempting 3-D Secure
authentication. If the score returned exceeds the allowable threshold, then the transaction is not submitted for
authentication.
Scenario:
• Fraud score received from scoring service exceeds configured threshold
Values:
• mdStatus = 8
• MPI ECI is empty
• Visa authorization ECI value is not relevant, because transaction cannot be continued with Visa infrastructure
(note that this must be verified from Visa)

Pending Transactions
If MPI has passed the PAReq or 2.x CReq to the ACS, the browser session has also moved away from the MPI.
Sometimes, the control may never come back to the MPI, which means that there will be a pending transaction in the
database for the time beeing.
Modirum MPI does not include a timer to react to the pending transactions, but this functionality needs to be
implemented at the merchant site.
The background direct post feature in MPI Server can be used to avoid using the user browser for redirection in
return. (This won’t help any if user does not return from ACS).
The control flow using background direct post feature is:
1. ACS Posts the PARes (2.x CRes) back to MPI Server via the user browser using the redirection
2. MPI Server determines the status of the transaction and post the status values to merchant payment page
using a background session directly from MPI Server to the Merchant payment page server.
3. Merchant server continues with authorization and after the authorization displays the confirmation page to
the session opened by the Merchant Server. The Merchant Server passes the page unchanged to the user
browser as a response page to the post in step 1.

Summary
The following table summarizes the end status scenarios of the Modirum MPI. The description of ECI values should
be placed into the authorization message in the case of Visa.
MPI provides ECI value only if it receives it from the ACS. If merchant receives the ECI from the MPI, that is the
value that should be placed in the authorization message. If the ECI value received from the merchant is empty, the
merchant should fill out the value prior to sending the authorization message. The suggested values are listed in Visa
ECI column. Since these values are schema and Visa region specific, please verify the rules with your local Visa
representative. MasterCard uses only ECI values 0,1,2 etc.Especially U cases (mdStatus=5) check schema published
rules, what if the best action, default recommended to not make authorization.

• Process transactions normally for mdStatus 1, 2(3DS1 only) and 4
• Never shall process transactions for mdStatus 0, 5,6, 8 and 9x

3 XML Interface

Another way to add 3-D Secure support to existing Merchant site is to use XML interface of the Modirum MPI.

3.1 EMVCo 3DS 2.x protocol control flow

Browser based control flow:
1. Merchant payment page asks the user all the relevant payment data, such as card number, expiry, etc.
2. Merchant payment page creates EnrollementRequest (initial) calculates signature of Message element to be
posted to Modirum MPI, sets the signature to ModirumMPI message and posts the ModirumMPI XML to
Modirum MPI with Content-Type=application/xml. Note that Merchant should set termUrl parameter in the
request message. It should represent Merchant page url, where ACS will post (via user browser) CRes message
after user authentication.
3. Modirum MPI checks the card participation from the 3-D Secure directory published ranges and then:
a. If range participates in 3DS Method merchant is returned EnrollmentResponse with mdStatus=50
(perform 3DS method and continue with enrollment request). Upon receiving such response merchant
shall take html content from field TDSMethodContent and render user an intermediate page where this
content is placed into an invisible iframe and wait about 2..3 seconds (or until 3DSMethodcompletion
but normally not longer than 5 seconds (Note: EMVCo spec says up to 10 seconds). The merchant
supplied threeDSMethodNotificationURL is notified.
b. If merchant used TDS2.threeDSMethodNotificationURL in initial request then send new
EnrollmentRequest (continue) filling in only txId, xid, transientData (cloud mode only) and
TDS2.threeDSCompInd attribute if merchant used TDS2.threeDSMethodNotificationURL on its
own.
c. If range does not participate in 3DS Method then continues directly to step 4
4. MPI returns
a. If no errors and challenge was requested then response message contains field RedirectToACSForm
filled with content. It has to be sent to user browser so that user browser posts CReq to ACS for
authentication.
b. With error or final (frictionless) authentication results, 3DS flow ends. Based on results
merchant determines if to proceed authorization or not.
5. After ACS is finished with the user authentication, ACS returns the control to the Merchant. Merchant receives
CRes to termUrl (set in initial request) and sends PAResValidationRequest to the MPI with CRes field filled
with CRes content received. The MPI Server verifies the CRes and matches it with appropriate RReq from
directory and responds to Merchant with final outcome.
6. Based on returned parameters Merchant proceeds with transaction authorization or stops the transaction in
caseof error or authentication failure.

Diagram to illustrate 3DS2 XML API browser flow. Blue lines server to server communications, green lines user
browser redirects. Dashed lines when prior authentication 3DS method is required by ACS.

3.2 XML Parameters to be posted to MPI/3DS Server

The following table describes the XML parameters to be posted from the payment page to Modirum MPI. Interface
version has been upgraded to 4.0 which utilizes a signature element instead of a digest. The software still supports 3.0 and 2.0, but it is not recommended to use versions before 3.0.

3.3 Calculation of the Signature
Signatures shall be calculated and verified according to documentation https://www.w3.org/TR/xmldsig-core/
Canonicalization method to be used is http://www.w3.org/TR/2001/REC-xml-c14n-20010315 SignatureMethod
Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256”
DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"
The signed element is Message element referenced with its ID attribute named messageId. ID attribute is an attribute
which type in schema is defined as xsd:ID.
Messages sent by the merchant will be signed by the merchant’s private key and verified by the MPI using the
merchant’s certificate.
Note that the XML documents should be handled with namespace aware xml libraries (parser/serializer).
When the Message element is serialized and canonicalized it should also contain xmlns namespace attribute.
See from next section XML message with digest example. Canonicalized message starts for example as:
<Message xmlns="http://www.modirum.com/schemas/mpiapi" md="C62C2F592F1BCA32A24EA877CFF7A461"
merchantId="0000001" messageId="M1523010167533" version="4.0">…

public static byte[] sign(ModirumMPI root, Marshaller m, DocumentBuilderFactory dbf, PrivateKey
prik, java.security.cert.X509Certificate[] crts) throws Exception
{
org.apache.xml.security.Init.init();
org.w3c.dom.Document document = dbf.newDocumentBuilder().newDocument();
m.marshal(root, document);// apis.normalizeDOM(dom); dom nomralization is very slow uing instead
msg.setIdAttribute("messageId", true);
Element modirumMPI = document.getDocumentElement();
org.apache.xml.security.signature.XMLSignature xmlsigAp =new XMLSignature(document,
null,"http://www.w3.org/2001/04/xmldsig-more#rsa-sha256", "http://www.w3.org/TR/2001/REC-xml-c14n20010315");
Element sigel = xmlsigAp.getElement();
modirumMPI.appendChild(sigel);
Element msg = (Element)modirumMPI.getFirstChild();
msg.setIdAttribute("messageId", true); // setting id attribute instead of dom normalization
xmlsigAp.addDocument("#" + msg.getAttribute("messageId"),
null, "http://www.w3.org/2001/04/xmlenc#sha256", null, null);
for(int i = 0; crts != null && i < crts.length; i++)
{
xmlsigAp.addKeyInfo(crts[i]);
}
xmlsigAp.sign(prik);
ByteArrayOutputStream bos = new ByteArrayOutputStream(4096);
TransformerFactory transfac = TransformerFactory.newInstance();
Transformer trans = transfac.newTransformer();
trans.setOutputProperty(OutputKeys.OMIT_XML_DECLARATION, "no");
trans.setOutputProperty(OutputKeys.INDENT, "no");
trans.setOutputProperty(OutputKeys.ENCODING, "utf-8");
DOMSource source = new DOMSource(document);
trans.transform(source, new StreamResult(bos));
return bos.toByteArray();
}

Notes: Never calculate signature in user browser using JavaScript or other script. Or You will expose Your private key to
the world. Before passing data to SHA-256 RSA signature function ensure string data is converted to bytes using UTF- 8
character encoding. Signatures should be calculated and checked during any communication with MPI be it request or response.

3.4 XML parameters to be returned to Merchant

3.5 Example XML messages for EMVCo protocol 2.x browser flow

3.5.1 Initial request to MPI

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<ModirumMPI xmlns="http://www.modirum.com/schemas/mpiapi" xmlns:ns2="http://www.w3.org/2000/09/xmldsig#">
    <Message md="DAC72539C87D964E6649C4E0FD12336A" merchantId="sys1331720664552" messageId="M1702393329407" version="4.0">
        <Request>
            <EnrollmentRequest>
                <Parameters>
                    <pan>4016360000000002</pan>
                    <expiry>2912</expiry>
                    <deviceCategory>0</deviceCategory>
                    <purchAmount>15000</purchAmount>
                    <exponent>2</exponent>
                    <description>DVD Movies</description>
                    <currency>978</currency>
                    <termUrl>https://alphaecommerce-test.cardlink.gr:443/coffeehouse/MerchantHandler2;jsessionid=DAC72539C87D964E6649C4E0FD12336A</termUrl>
                    <TDS2Attributes>
                        <Attribute name="TDS2_Navigator_jsEnabled">true</Attribute>
                        <Attribute name="TDS2.cardholderName">Test Customer</Attribute>
                        <Attribute name="TDS2.email">test@cardlink.gr</Attribute>
                        <Attribute name="TDS2.mobilePhone">30-6940123456</Attribute>
                        <Attribute name="TDS2.billAddrCity">C</Attribute>
                        <Attribute name="TDS2.billAddrCountry">300</Attribute>
                        <Attribute name="TDS2.billAddrLine1">S</Attribute>
                        <Attribute name="TDS2.billAddrPostCode">12345</Attribute>
                    </TDS2Attributes>
                    <xid>WZjpyh0QU+AG4NuEl/EL+6cvPWk=</xid>
                    <merchantTxId>7ed4fc96-b390-4404-9053-f8a796a4c303</merchantTxId>
                </Parameters>
            </EnrollmentRequest>
        </Request>
    </Message>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo>
            <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2006/12/xml-c14n11"/>
            <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
            <ds:Reference URI="#M1702393329407">
            <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
            <ds:DigestValue>WGF/Rx7uYs7h6Ur1XzR7P3TwkRW15UKwn+4GLFGEZ4A=</ds:DigestValue>
            </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>
        5rrF8aLDBQ/skS4QQOHDiOOnPRPyPRNseIjhIQlFEjPnPTwJGwDvKI+L/W7cHxt+YO+aC1c/MUD9
        MpA1LiUNRps3R/sEZ/20Ss9bYqAT50nnGlsBGhHBJ6IuZlBGFioGw6aXM6D+j+DY/pLg2j2jn/fb
        ZreC2d2mGm4Xxnr2P1qyYfAh2Vgq5yel+U5n3Jjcm5wnIQ0+QdE752ydf+hROC/RP7wLf3D8Kdgf
        df3/mDZe30laYbsRa9xnePrQgq5B+dOrIlbfs36I4UOtEHprevPoPeKjLbMuCFH5oP59KQqxk6MC
        dGmdou/GGLDPh0GF2/1AJ+IWP38AFc+9Dg+M3g==
        </ds:SignatureValue>
        <ds:KeyInfo>
            <ds:X509Data>
            <ds:X509Certificate>
            MIIESzCCAzOgAwIBAgIJANq6Drpt8SB5MA0GCSqGSIb3DQEBCwUAMHYxCzAJBgNVBAYTAkVFMREw
            ...
            tmcgicP7sLWd4Pu1fAx+51tgDSGjh2m0SSDz2rv7CrJ44RXIUOWAMWbC4myssyea3t+GrSvWrDGH
            RLXZUNmvy+zFSB+QFWEW2nlfYI8=
            </ds:X509Certificate>
            </ds:X509Data>
        </ds:KeyInfo>
    </ds:Signature>
</ModirumMPI>

3.5.2 Response from MPI with 3DS Method redirection form

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<ModirumMPI xmlns="http://www.modirum.com/schemas/mpiapi" xmlns:ns2="http://www.w3.org/2000/09/xmldsig#">
    <Message md="DAC72539C87D964E6649C4E0FD12336A" merchantId="sys1331720664552" messageId="M1702393329407" version="4.0">
        <Response>
            <Parameters>
                <xid>WZjpyh0QU+AG4NuEl/EL+6cvPWk=</xid>
                <merchantTxId>7ed4fc96-b390-4404-9053-f8a796a4c303</merchantTxId>
                <mdStatus>50</mdStatus>
                <mdErrorMsg>3DS method requested before enrollment</mdErrorMsg>
                <enrollmenStatus>-</enrollmenStatus>
                <authenticationStatus>-</authenticationStatus>
                <txId>8470001</txId>
                <protocol>3DS2.2.0</protocol>
                <cardType>1</cardType>
            </Parameters>
            <TDSMethodContent><iframe id="tdsMmethodTgtFrame" name="tdsMmethodTgtFrame" style="visibility: hidden; width: 1px; height: 1px;" xmlns="http://www.w3.org/1999/xhtml">
            <!--.-->
            </iframe><form id="tdsMmethodForm" name="tdsMmethodForm" action="https://3ds-acs.test.modirum.com/mdpayacs/3ds-method" method="post" target="tdsMmethodTgtFrame">
            <input type="hidden" name="3DSMethodData" value="eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogIjY1ZmZkNjEyLTMyNWItNTQwNS04MDAwLTAwMDAwMDgxM2RmMSIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA6ICJodHRwczovL2FscGhhZWNvbW1lcmNlLXRlc3QuY2FyZGxpbmsuZ3IvbWRwYXltcGkvTWVyY2hhbnRTZXJ2ZXI_bW49WSZ0eGlkPTg0NzAwMDEmZGlnZXN0PWNYRzJtQ1VmS0NQNkxWS0d4MyUyRmZmV3FCbERzSFg4U3hDcFdzaFRNQkZZYyUzRCIgfQ"><input type="hidden" name="threeDSMethodData" value="eyAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogIjY1ZmZkNjEyLTMyNWItNTQwNS04MDAwLTAwMDAwMDgxM2RmMSIsICJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIiA6ICJodHRwczovL2FscGhhZWNvbW1lcmNlLXRlc3QuY2FyZGxpbmsuZ3IvbWRwYXltcGkvTWVyY2hhbnRTZXJ2ZXI_bW49WSZ0eGlkPTg0NzAwMDEmZGlnZXN0PWNYRzJtQ1VmS0NQNkxWS0d4MyUyRmZmV3FCbERzSFg4U3hDcFdzaFRNQkZZYyUzRCIgfQ"><script type="text/javascript">
            document.getElementById("tdsMmethodForm").submit();
            </script>
            </form></TDSMethodContent>
            <TDS2RespAttributes>
            <Attribute name="TDS2.threeDSServerTransID">65ffd612-325b-5405-8000-000000813df1</Attribute>
            </TDS2RespAttributes>
        </Response>
    </Message>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo>
        <ds:CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
        <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
        <ds:Reference URI="#M1702393329407">
        <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
        <ds:DigestValue>ADDCwdQywS2Y4X8wXI8U3qHcpX5vxWTB0lvteHSCvFA=</ds:DigestValue>
        </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>
        cO3oGG2jnuDKc1Ut9Pkeu7rfFm/SPuYaOf9YFP6UfQlknt+Txah2qBsKtrFPCM7k7ZexINgS/RiB
        V4C8/FLCzYgI0CnZLYsUOQCKixCp6NV2/4ijfBo5oYlbG2cDcjUVHkkUFcca1yM6Ue6qna7M26iB
        szdaXP2IYvd42gOKeg8JlQdKZVlXkBDV7OOERjMdJlq2wQo8uxQ7zMaL2345PBnJTqm8w/SEu0+T
        BPXW9PomUs0NgTvEc80VvlN7BXs46ptVlqD/ijwR5RN7RE/v9WzwZ1fh6JrsKMH8V4kjtZx9P+lx
        x/aToIYg8QSLxhMnP4gSyZNXpX/74xZEGCHOnmjW9XTsKWH7QoKOX07WscQuLNZKyNKdpAumkDfD
        Cg0+UR1FjKxzGwvaAiB2WptDKEpXlttAINYkruvzK3vI5qAn4aRxvq5kIDq0gI1AoAJGmh1mpGvd
        P1J/MTql7V/duJOIBaBxdvaZfPKh7hihU+a6AfavwcuhZpzBOSkMHzn4
        </ds:SignatureValue>
        <ds:KeyInfo>
        <ds:X509Data>
        <ds:X509Certificate>
        MIIEVTCCAr0CBGQm1T4wDQYJKoZIhvcNAQELBQAwbzEfMB0GA1UEAxMWQ2FyZGxpbmtNZXNzYWdl
        ...
        uU46fkKXexUD92aI/d/F/Vv/LZORZ8Wt4eIEmpmWW08Xww7LEqDpzHyGZ5BNuHf6r5Yb1rmS1Z/L
        PRu+VcI4Hy8081eP5rAcvjUTCjp6A9EwbDKsjH5K
        </ds:X509Certificate>
        </ds:X509Data>
        </ds:KeyInfo>
    </ds:Signature>
</ModirumMPI>

3.5.3 Request to MPI after 3DS Method

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<ModirumMPI xmlns="http://www.modirum.com/schemas/mpiapi" xmlns:ns2="http://www.w3.org/2000/09/xmldsig#">
    <Message merchantId="sys1331720664552" messageId="M1702393332315" version="4.0">
        <Request>
            <EnrollmentRequest>
                <Parameters>
                    <txId>8470001</txId>
                    <xid>WZjpyh0QU+AG4NuEl/EL+6cvPWk=</xid>
                    <merchantTxId>7ed4fc96-b390-4404-9053-f8a796a4c303</merchantTxId>
                </Parameters>
            </EnrollmentRequest>
        </Request>
    </Message>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo>
            <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2006/12/xml-c14n11"/>
            <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
            <ds:Reference URI="#M1702393332315">
            <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
            <ds:DigestValue>38TlY7uGFW1rwHRgeyM5+qTIJZJcgk6dItquolszOnA=</ds:DigestValue>
            </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>
        yDTMhLcG1aBkjGYige4cLR14TP8prE6CvvV0UCroLiUZ/+wpOzsgS8+F5GqJ3Rc3F2lsl6I/sxHW
        wk0kTQ2FU97sXQP/FB8LzrNmhIiJKXZc9Q0P6UBgyromCq8QtUwKPhWx84hxHTFN4/+QzHU/HZ7Y
        4GAht9EUQeFf+mTyz4ZEM5I8/jR6tJWBbbxZPk4pSsLeOwjJWLbIm1wu4OtnUDWWO5kw7BLB7lL8
        +VgB4tAq4sd+paAmHxBJPli1jQOErMfGUnVCTSnbhZZ4mNph1UaNPx+rclySHJjbmN+A3P5XjWTG
        g5nLH7jmJIGQn5cG6RsifNY7k+gQsK0hpWMQpA==
        </ds:SignatureValue>
        <ds:KeyInfo>
            <ds:X509Data>
            <ds:X509Certificate>
            MIIESzCCAzOgAwIBAgIJANq6Drpt8SB5MA0GCSqGSIb3DQEBCwUAMHYxCzAJBgNVBAYTAkVFMREw
            ...
            tmcgicP7sLWd4Pu1fAx+51tgDSGjh2m0SSDz2rv7CrJ44RXIUOWAMWbC4myssyea3t+GrSvWrDGH
            RLXZUNmvy+zFSB+QFWEW2nlfYI8=
            </ds:X509Certificate>
            </ds:X509Data>
        </ds:KeyInfo>
    </ds:Signature>
</ModirumMPI>

3.5.4 Response from MPI with CReq redirection form to ACS

<?xml version="1.0" encoding="UTF-8" standalone="no"?><ModirumMPI xmlns="http://www.modirum.com/schemas/mpiapi" xmlns:ns2="http://www.w3.org/2000/09/xmldsig#"><Message md="DAC72539C87D964E6649C4E0FD12336A" merchantId="sys1331720664552" messageId="M1702393332315" version="4.0"><Response><Parameters><xid>WZjpyh0QU+AG4NuEl/EL+6cvPWk=</xid><merchantTxId>7ed4fc96-b390-4404-9053-f8a796a4c303</merchantTxId><mdStatus>9</mdStatus><mdErrorMsg>To be redirected to ACS</mdErrorMsg><enrollmenStatus>Y</enrollmenStatus><authenticationStatus>C</authenticationStatus><txId>8470001</txId><protocol>3DS2.2.0</protocol><cardType>1</cardType></Parameters><redirectToACSForm><html class="no-js" lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
<META http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta charset="utf-8">
<title>3D Secure Processing</title>
<link href="https://alphaecommerce-test.cardlink.gr/mdpaympi/static/mpi.css" rel="stylesheet" type="text/css">
</head>
<body>
<div id="main">
<div id="content">
<div id="order">
<h2>3D Secure Processing</h2>
<script src="https://alphaecommerce-test.cardlink.gr/mdpaympi/static/red.js" defer>/* needed for xsl to xhtml */</script>
<div id="spinner">
<img src="https://alphaecommerce-test.cardlink.gr/mdpaympi/static/preloader.gif" alt="Please wait..">
</div>
<img src="https://alphaecommerce-test.cardlink.gr/mdpaympi/static/verifiedbyvisa.png" alt="Verified by VISA">
<div id="formdiv">
<div>
<form id="webform0" name="red2ACSv2" method="POST" action="https://3ds-acs.test.modirum.com/mdpayacs/vW-8AVIG6hg_PKD_/creq;token=293545061.1702393335.pwBrIRuiK9HT3-KALa9nfjto8RiOzk9d_dK4yg-N_xU" accept_charset="UTF-8">
<input type="hidden" name="creq" value="ewogICAiYWNzVHJhbnNJRCIgOiAiODQ4MTEwMjAtNzY1YS00ZjU1LWFlMzctMDgwNTIwZjVkNDg4IiwKICAgImNoYWxsZW5nZVdpbmRvd1NpemUiIDogIjAzIiwKICAgIm1lc3NhZ2VUeXBlIiA6ICJDUmVxIiwKICAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjIuMCIsCiAgICJ0aHJlZURTU2VydmVyVHJhbnNJRCIgOiAiNjVmZmQ2MTItMzI1Yi01NDA1LTgwMDAtMDAwMDAwODEzZGYxIgp9"><input type="hidden" name="threeDSSessionData" value="DAC72539C87D964E6649C4E0FD12336A"><script type="text/javascript">
hideAndSubmitTimed('webform0');
</script>
<noscript>
<div align="center">
<b>Javascript is turned off or not supported!</b>
<br>
</div>
</noscript>
<input type="submit" name="submitBtn" id="submitBtn" value="Please click here to continue">
</form>
</div>
</div>
<noscript>
<div align="center">
<b>Javascript is turned off or not supported!</b>
<br>
</div>
</noscript>
</div>
<div id="content-footer"></div>
</div>
</div>
</body>
</html>
</redirectToACSForm><redirectToACSFormData actionURL="https://3ds-acs.test.modirum.com/mdpayacs/vW-8AVIG6hg_PKD_/creq;token=293545061.1702393335.pwBrIRuiK9HT3-KALa9nfjto8RiOzk9d_dK4yg-N_xU"><field name="creq">ewogICAiYWNzVHJhbnNJRCIgOiAiODQ4MTEwMjAtNzY1YS00ZjU1LWFlMzctMDgwNTIwZjVkNDg4IiwKICAgImNoYWxsZW5nZVdpbmRvd1NpemUiIDogIjAzIiwKICAgIm1lc3NhZ2VUeXBlIiA6ICJDUmVxIiwKICAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjIuMCIsCiAgICJ0aHJlZURTU2VydmVyVHJhbnNJRCIgOiAiNjVmZmQ2MTItMzI1Yi01NDA1LTgwMDAtMDAwMDAwODEzZGYxIgp9</field><field name="threeDSSessionData">DAC72539C87D964E6649C4E0FD12336A</field></redirectToACSFormData><TDS2RespAttributes><Attribute name="TDS2.transStatus">C</Attribute><Attribute name="TDS2.threeDSServerTransID">65ffd612-325b-5405-8000-000000813df1</Attribute><Attribute name="TDS2.dsTransID">7205089f-53c0-53cb-8000-00000a54b12d</Attribute><Attribute name="TDS2.acsTransID">84811020-765a-4f55-ae37-080520f5d488</Attribute><Attribute name="TDS2.acsReferenceNumber">3DS_LOA_ACS_MOMD_020100_00061</Attribute><Attribute name="TDS2.messageVersion">2.2.0</Attribute><Attribute name="TDS2.acsChallengeMandated">N</Attribute><Attribute name="TDS2.authenticationType">01</Attribute><Attribute name="TDS2.acsOperatorID">3DS_LOA_ACS_MOMD_020100_00061</Attribute><Attribute name="TDS2.acsUrl">https://3ds-acs.test.modirum.com/mdpayacs/vW-8AVIG6hg_PKD_/creq;token=293545061.1702393335.pwBrIRuiK9HT3-KALa9nfjto8RiOzk9d_dK4yg-N_xU</Attribute><Attribute name="TDS2.AReqToResMillis">808</Attribute></TDS2RespAttributes></Response></Message><ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
<ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
<ds:Reference URI="#M1702393332315">
<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
<ds:DigestValue>aPnWCtW+f6WThQPDswl2i63Y0tdE/ur8N0YL3mvg/kY=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>
PlFGtFZCWUqwWqWk94JzF4JKOTP+X31k6SjHX1JhFuuAFHkDzFoEcyVdSdsCcZaf/QmXaQ9DIlfY
7F8mDTuUY4IDV69LfQ3JbE+DC2Eu19cU2spGNFZXXO7WVhFZ1hsOcnr2tKE3YlNpHwAhVBGpvSAS
xYPgLx/0aCLOlwcjcIY6eFmGZLrEzGpfqTH7rrwv/RKMOzEBYMK+lsSJeovH8B05Pgp37Xnj5e/b
pfnEzdxiJJ2rhOozJsv9sixVqrZvQwNFK7PiAf4NvxijpEdPCvCwLzX4a6R+5Xv7Zw2pYeNA+yhV
JbWth0efqNOoZu8clDB0Nb4UHR2FtADyIelAGn8Y3/QhtAnR63BRRPSMP9C0634hrqnrEtOuvlqB
o36NTFiwnI/UAic59f2X3tQnx8+0LyBsDSSyteq1N0WLhzhfZzL8LJQrOmR6fxW5i/OjS0Pv6at5
gu+3ibmikmPPl+VriNYXXJ5Ub6hnuquvxXpwKg2Dp9fSYqrFmOSEZ4xK
</ds:SignatureValue>
<ds:KeyInfo>
<ds:X509Data>
<ds:X509Certificate>
MIIEVTCCAr0CBGQm1T4wDQYJKoZIhvcNAQELBQAwbzEfMB0GA1UEAxMWQ2FyZGxpbmtNZXNzYWdl
...
uU46fkKXexUD92aI/d/F/Vv/LZORZ8Wt4eIEmpmWW08Xww7LEqDpzHyGZ5BNuHf6r5Yb1rmS1Z/L
PRu+VcI4Hy8081eP5rAcvjUTCjp6A9EwbDKsjH5K
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</ds:Signature></ModirumMPI>

3.5.5 Request to MPI with CRes

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<ModirumMPI xmlns="http://www.modirum.com/schemas/mpiapi" xmlns:ns2="http://www.w3.org/2000/09/xmldsig#">
    <Message md="DAC72539C87D964E6649C4E0FD12336A" merchantId="sys1331720664552" messageId="M1702393332315" version="4.0">
        <Request>
            <PAResValidationRequest>
            <cres>ewogICJhY3NUcmFuc0lEIiA6ICI4NDgxMTAyMC03NjVhLTRmNTUtYWUzNy0wODA1MjBmNWQ0ODgiLAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjIuMCIsCiAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIiA6ICI2NWZmZDYxMi0zMjViLTU0MDUtODAwMC0wMDAwMDA4MTNkZjEiLAogICJ0cmFuc1N0YXR1cyIgOiAiWSIKfQ</cres>
            </PAResValidationRequest>
        </Request>
    </Message>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo>
            <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2006/12/xml-c14n11"/>
            <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
            <ds:Reference URI="#M1702393332315">
            <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
            <ds:DigestValue>lJ9hxva3kAv1P6pbJQQ0XRp8uPWeSu8JwJe4rabhxGw=</ds:DigestValue>
            </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>
        SRfxtIHV+j8jM0eIvhnSpjsPqbg0nKWSc2H9QWHJ+/mbOmB3UJom8w8hFEnJzGtwPl1g8FD9Jbms
        xqRHFPmOgVT0cLTZK2qzXATSwVZO/uQNBPlYCEPYmfZKEX57661Zr7GKhuQyBs0wU3dot0lEQGPo
        ne9Oi+p+1r410GhoGvwGXQIDFxtJfmw9nvGNstiyNJ3ni7M8qUcdnzUEbmCCzsRnJPrY7Ys79/Ov
        c13X7tEXVsSHo5Gt70q0ecmIpRGDCClNhHQPEnzN3lDWmVxCvETuz/h263lTOcu3Oi2u4hw1Y4vp
        EAS0EwqlE8to5mLDgAGFIXuzur6AdzuIyqnq3Q==
        </ds:SignatureValue>
        <ds:KeyInfo>
            <ds:X509Data>
            <ds:X509Certificate>
            MIIESzCCAzOgAwIBAgIJANq6Drpt8SB5MA0GCSqGSIb3DQEBCwUAMHYxCzAJBgNVBAYTAkVFMREw
            ...
            tmcgicP7sLWd4Pu1fAx+51tgDSGjh2m0SSDz2rv7CrJ44RXIUOWAMWbC4myssyea3t+GrSvWrDGH
            RLXZUNmvy+zFSB+QFWEW2nlfYI8=
            </ds:X509Certificate>
            </ds:X509Data>
        </ds:KeyInfo>
    </ds:Signature>
</ModirumMPI>

3.5.6 Final response from MPI

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<ModirumMPI xmlns="http://www.modirum.com/schemas/mpiapi" xmlns:ns2="http://www.w3.org/2000/09/xmldsig#">
<Message md="DAC72539C87D964E6649C4E0FD12336A" merchantId="sys1331720664552" messageId="M1702393332315" version="4.0">
<Response>
<Parameters>
<xid>WZjpyh0QU+AG4NuEl/EL+6cvPWk=</xid>
<merchantTxId>7ed4fc96-b390-4404-9053-f8a796a4c303</merchantTxId>
<mdStatus>1</mdStatus>
<mdErrorMsg>Y-status/Challenge authentication via ACS: https://3ds-acs.test.modirum.com/mdpayacs/vW-8AVIG6hg_PKD_/creq;token=293545061.17023</mdErrorMsg>
<enrollmenStatus>Y</enrollmenStatus>
<authenticationStatus>

At VPOS side there are both validations implemented. If the digest value is present, then VPOS validates the authentication of message using the digest and merchant shared secret.

Similar validation of the digest should also be made from the merchant for the received response message.

Version 2.1 
Base64(SHA256((utf8bytes(canonicalize(Message))+utf8bytes(sharedSecret)))), to be used only if the XML password is not used. The canonicalization method to be used is http://www.w3.org/TR/2001/REC-xml-c14n-20010315

Note that the XML documents should be handled with namespace aware xml libraries (parser/serializer).  When the Message element is serialized and canonicalized it should contain xmlns namespace attribute.

For example a non canonicalized Message element

<Message version="2.1" messageId="M1627047946727" lang="en" timeStamp="2021-07-23T16:45:46.000+03:00">
  <SaleRequest>
    <Authentication>
      <Mid>0000001</Mid>
    </Authentication>
    <OrderInfo>
      <OrderId>1627047728798</OrderId>
      <OrderDesc></OrderDesc>
      <OrderAmount>1.25</OrderAmount>
      <Currency>EUR</Currency>
    </OrderInfo>
    <PaymentInfo>
      <PayMethod>visa</PayMethod>
      <CardPan>332211223344</CardPan>
      <CardExpDate>2206</CardExpDate>
      <CardCvv2>756</CardCvv2>
      <CardHolderName>John Smith</CardHolderName>
    </PaymentInfo>
  </SaleRequest>
</Message>

Below is the canonicalized version of Message element (attributes ordered and default xmlns defined):

<Message xmlns=http://www.modirum.com/schemas/vposxmlapi41 xmlns:ns2=http://www.w3.org/2000/09/xmldsig# lang="en" messageId="M1627047946727" timeStamp="2021-07-23T16:45:46.000+03:00" version="2.1">
  <SaleRequest>
    <Authentication>
      <Mid>0000001</Mid>
    </Authentication>
    <OrderInfo>
      <OrderId>1627047728798</OrderId>
      <OrderDesc></OrderDesc>
      <OrderAmount>1.25</OrderAmount>
      <Currency>EUR</Currency>
    </OrderInfo>
    <PaymentInfo>
      <PayMethod>visa</PayMethod>
      <CardPan>332211223344</CardPan>
      <CardExpDate>2206</CardExpDate>
      <CardCvv2>756</CardCvv2>
      <CardHolderName>John Smith</CardHolderName>
    </PaymentInfo>
  </SaleRequest>
</Message>

Also take note that in canonicalized form element attributes are ordered lexicographically see https://www.w3.org/TR/2001/REC-xml-c14n-20010315#DocumentOrder

Note for XML API with Three D Secure:

This is 2 step processing at first step merchant should implement MPI plugin session as decribed in Modirum MPI manual and obtain the Three D Secure authentication results from there and then next step is to fill the corresponding values to XML API ThreeDSecure element and proceed with XML api request to VPOS.

XML API plugin example message and digest

Secret=SecRetDigest1

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VPOS xmlns=http://www.modirum.com/schemas/vposxmlapi41 xmlns:ns2=http://www.w3.org/2000/09/xmldsig#>
  <Message version="2.1" messageId="M1560776758348" timeStamp="2019-06-17T16:05:58.348+03:00">
    <SaleRequest>
      <Authentication>
        <Mid>0000001</Mid>
      </Authentication>
      <OrderInfo>
        <OrderId>1560776271083</OrderId>
        <OrderDesc>Test</OrderDesc>
        <OrderAmount>1.25</OrderAmount>
        <Currency>EUR</Currency>
        <PayerEmail>
        </PayerEmail>
      </OrderInfo>
      <PaymentInfo>
        <PayMethod>visa</PayMethod>
        <CardPan>4016000000002</CardPan>
        <CardExpDate>2206</CardExpDate>
        <CardCvv2>756</CardCvv2>
        <CardHolderName>John Smith</CardHolderName>
      </PaymentInfo>
    </SaleRequest>
  </Message>
  <Digest>xmSXBhrE99FqiP2b73S 0cS+oLrIi8+lng9IS9KmoWpM=</Digest>
</VPOS>

Message part canonicalized note xmlns added:

<Message xmlns=http://www.modirum.com/schemas/vposxmlapi41 xmlns:ns2=http://www.w3.o rg/2000/09/xmldsig# messageId="M1560776758348" timeStamp="2019-06-17T16:05:58.348+03:00" version="2.1">
  <SaleRequest>
    <Authentication>
      <Mid>0000001</Mid>
    </Authentication>
    <OrderInfo>
      <OrderId>1560776271083</OrderId>
      <OrderDesc>Test</OrderDesc>
      <OrderAmount>1.25</OrderAmount>
      <Currency>EUR</Currency>
      <PayerEmail></PayerEmail>
    </OrderInfo>
    <PaymentInfo>
      <PayMethod>visa</PayMethod>
      <CardPan>4016000000002</CardPan>
      <CardExpDate>2206</CardExpDate>
      <CardCvv2>756</CardCvv2>
      <CardHolderName>John Smith</CardHolderName>
    </PaymentInfo>
  </SaleRequest>
</Message>
SecRetDigest1

Then append SecRetDigest1 and apply sha2-256 function.
You will get digest
<Digest>xmSXBhrE99FqiP2b73S0cS+oLrIi8+lng9IS9KmoWpM=</Digest>

Response example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VPOS xmlns=http://www.modirum.com/schemas/vposxmlapi41 xmlns:ns2=http://www.w3.org/2000/09/xmldsig#>
  <Message version="2.1" messageId="M1560776758348" timeStamp="2019-06-17T16:05:58.517+03:00">
    <SaleResponse>
      <OrderId>1560776271083</OrderId>
      <OrderAmount>1.25</OrderAmount>
      <Currency>EUR</Currency>
      <PaymentTotal>1.25</PaymentTotal>
      <Status>CAPTURED</Status>
      <TxId>927703881</TxId>
      <PaymentRef>104040</PaymentRef>
      <RiskScore>10</RiskScore>
      <Description>OK, CAPTURED response code 00</Description>
      <Attribute  name="EXTACQUIRERID">014</Attribute>
    </SaleResponse>
  </Message>
  <Digest>oavTfZECv1L8hKcjw0m V+bOvIjSdq+UNSNU7/xRvnAA=</Digest>
</VPOS>

Signatures shall be calculated and verified according to documentation https://www.w3.org/TR/xmldsig-core/

Canonicalization method to be used is http://www.w3.org/TR/2001/REC-xml-c14n-20010315

SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"

DigestMethod  Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"

The signed element is Message element referenced with its ID attribute named  messageId.

ID attribute is an attribute which type in schema is defined as xsd:ID.

Messages sent by merchant are signed by merchant private key and verified with merchant certificate.

Messages sent by VPOS service are signed by service provider private key and validated with service provider provided certificate.

XML API plugin example message and signature calculation

Here is an example request message to VPOS and how the signature is calculated.

(used apache santuario)

Merchant Private key PKCS8:

—–BEGIN PRIVATE KEY—–

MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDaX7Jd16os2Mti

cXHXGjanQ3fDSwwoRRhVWi12+SiFDMVBpBwZEGdmHopO5cpSGptFxeau7HqGfSaq

5NoI01pbf/OPFpstO4mSlIBj2OO9wzcW2yNeAQjzycEQmgNr1UQACUmXsNzBZZ2m

rcddkdRpxfHPaZx+GIYMdemFY7G0yBXsG0Dq+3hi9kqyGYlAN3PFsqCEdwD3H8qd

5UKz4wKEYhuqhKBZZoGBBUQZt7X9plwdMoZhtqbJIJTpda5Og/yNxkSjiTQrOMnt

vSl5dAQ8dGxoFaKAdvaE09eqt0F6RI76qyUU3B0PKBVB/kIYhvFSvJtef6a8fF4S

y56VOMptAgMBAAECggEBAM9tj1Qsg21OEQNVlzknoTqIj75mDwpBd7e7jOwyCBc5

5jVP2ZDFUDJkWCRRijkrJMrGDTWjU09kmdJCyAkSGgZIJ+aHJqd0ol0lyj8NymZ6

hF2lkpa8jPBleIp4gT9wuMMAD3OTgF4EVBf7giCTYR2H9QV74Da2vL4hUsxtwmNg

2jQjjHTsVA/ESjiyGveh1X6+GV6CsTZsoAWLlOhuDHiOMuOXDBmn9JjArFsl2W4X

yrtrDx68nVdPdIH2LzIrBzqRG6tB9RpNQNWGs/IxuEUG07fLMGzQiureOTUm/ybt

ZrO9Ab59tzWXCFXHljsGJu9SnZuPNOT0L8PuJIxKOIECgYEA9w6hdFaVr0HMnQtX

ndtZQfiqNnQMymV0mR9gtyw20/krOW5yt7WqhrzzTB72m4bsm27Yz3Dn0jfhQ1h5

zyihrT+FGeF6jS6+Hr3FXFyMizxH9AZPl13UmZo1fKxeoL+sE5PppFE9Qlsz0TBp

2phlVjzLI7i3KOu8Hyzt/rafZDkCgYEA4kdFMSHTQGLounpPauKaVi8v9TjyFdST

qSuQ0pMG4R9xuZ0x52L081goYmxo4jDo7P+m3iHDFdJqg+D7aAVay4Hv0PGKIq8G

vOAXm6mnXBaIMDVMnTRtqRynDoo2qKp9UU2Sv4D0L6Zbm9axDxMvqXCa8Lz5Kbnh

zJufUAwzn9UCgYEAkboGkDn2Zv8X81ZaYxmcZ6aGuEHxvXzkruFsSf+Bg71IusKk

ViqJIJrZo//rlMecTv6uUoYVp9EgRXott30PCMMb/q0afaahrD5h6N4KZKK1CoKi

dfV5zvTAMf72fjkxBgdMXIky6i4jvXOiLLeRprGLXVG6cB/EwlrdM06DbDkCgYBc

TdJt3mx8gVyKZUZsRY/LxGf90oL+YL7zbXAgVhWiU99iZjtrNjTR545hx/NpAaai

tw7s4jzgc/s7XNVxc228Qn7/buh4iYloFsnKmARLTm2zrKpaHn71U1jaV4tAdnu0

ZL6OHB6AKY6JHaUQjzUMG4E43v2NBeSUQI9WagPNGQKBgDj5qk4Jauy8zg/IBkXD

eJsgwGrMH7o1vj2Uhcd2K2NrxO3qRaJitNXH+cso836/Ez///kdepX3hQ3gKZS7i

aGhDFF3r0LU2OmskhoDSyhzVlCgsXbW1skFwL3Y161uYHwgpkFqrAODONXLu3PBd

S8jJbKkA3lQnmCCbET3NLfIV

—–END PRIVATE KEY—–

Merchant certificate X509:

—–BEGIN CERTIFICATE—–

MIIDuzCCAqOgAwIBAgIJANh5ptk5BWu5MA0GCSqGSIb3DQEBCwUAMHQxCzAJBgNV

BAYTAkVFMREwDwYDVQQIDAhNeSBTdGF0ZTEQMA4GA1UEBwwHbXkgQ2l0eTEVMBMG

A1UECgwMQ29tcGFueSBOYW1lMRAwDgYDVQQLDAc3NzExMjIzMRcwFQYDVQQDDA53

d3cubXlzaXRlLmNvbTAeFw0xNzAzMjkxNzM3MDFaFw0yMTAzMjgxNzM3MDFaMHQx

CzAJBgNVBAYTAkVFMREwDwYDVQQIDAhNeSBTdGF0ZTEQMA4GA1UEBwwHbXkgQ2l0

eTEVMBMGA1UECgwMQ29tcGFueSBOYW1lMRAwDgYDVQQLDAc3NzExMjIzMRcwFQYD

VQQDDA53d3cubXlzaXRlLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC

ggEBANpfsl3XqizYy2JxcdcaNqdDd8NLDChFGFVaLXb5KIUMxUGkHBkQZ2Yeik7l

ylIam0XF5q7seoZ9Jqrk2gjTWlt/848Wmy07iZKUgGPY473DNxbbI14BCPPJwRCa

A2vVRAAJSZew3MFlnaatx12R1GnF8c9pnH4Yhgx16YVjsbTIFewbQOr7eGL2SrIZ

iUA3c8WyoIR3APcfyp3lQrPjAoRiG6qEoFlmgYEFRBm3tf2mXB0yhmG2pskglOl1

rk6D/I3GRKOJNCs4ye29KXl0BDx0bGgVooB29oTT16q3QXpEjvqrJRTcHQ8oFUH+

QhiG8VK8m15/prx8XhLLnpU4ym0CAwEAAaNQME4wHQYDVR0OBBYEFJaXNDk3UIJT

7bjuedk13vmz62RjMB8GA1UdIwQYMBaAFJaXNDk3UIJT7bjuedk13vmz62RjMAwG

A1UdEwQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAJx7UBdBddBbJ8sz/Fa3YvDl

VR/GNTLp/haKC6G+FA97H5u2S7OGgXUnIX2T3M94QllhTykkzfr1zJeDZD+YrYyh

Ayp/ykHL0gk0tumHw8DN1BRmglRMc4QEXXHsx1HnMlcS0uE622M2+IQeDzDtLYpf

XL36Dqoik0hIuNSjlxqlIX4kBweA83Xx9IGyhsMhXHSS0BcPVmup97PTAs81YGOu

7vVgzyLBTHjabRktd0hVdm9+EJ/RMMFTW4XM+Ue2ekFx3uEX2B53ND6Mx5mtP/pi

bQ7/860FXUNdrHbcQCFufqhk7Ikr3+kv+Rqmh5DmrUbblpmXFvm6iLc6uYZqIvE=

—–END CERTIFICATE—–

Service provider certificate:

—–BEGIN CERTIFICATE—–

MIID5TCCAo0CBFjeXq8wDQYJKoZIhvcNAQELBQAwdzEoMCYGA1UEAxMfVlBPUyBERU1PIHZwb3Nh

ZG1pbi5tb2RpcnVtLmNvbTENMAsGA1UECxMEVlBPUzEQMA4GA1UEChMHTW9kaXJ1bTEQMA4GA1UE

BxMHVGFsbGlubjELMAkGA1UECBMCSE0xCzAJBgNVBAYTAkVFMB4XDTE3MDMzMTEzNTAzOVoXDTIy

MDkyMTEzNTAzOVowdzEoMCYGA1UEAxMfVlBPUyBERU1PIHZwb3NhZG1pbi5tb2RpcnVtLmNvbTEN

MAsGA1UECxMEVlBPUzEQMA4GA1UEChMHTW9kaXJ1bTEQMA4GA1UEBxMHVGFsbGlubjELMAkGA1UE

CBMCSE0xCzAJBgNVBAYTAkVFMIIBYjANBgkqhkiG9w0BAQEFAAOCAU8AMIIBSgKCAUEAyhFCdFGD

pchDXC7ryDUiMOlRHjce4N9e4hNUZ6+hTshRBTNeHqcTfhxKuiReaC6AVbQEbBYBGCUs8EQAWppK

RIB+ZnTytY8bhJqQ1YuiWvAN5cTBLoS2jE5vxf/Xx/+G+UhjfmK6XM0UKnQ4mR+MKM5/iSgV/Un7

ysHoLLepwefEUBQEODqAIsc6N5pMeeShT/66WEtxEkiXQPn48PXDRLLzSBzB247w03r+92WWrlVe

IMgTQc0kgx2gsgMziiqiUDSB69Bm/ugT81wDcUNklmbo8r3IsxtjOT+/HQ8Qbo4vQpJI7yzIcnvt

6U8Ub5TLjz4UmIBg8y6lY/kbJoxA/4n/M+1MwZqgM7cKGi5lG429A3h/1g2zhQ8bZBexnY5FLW1G

PTCS4ahE67ZYl8CWXjoDAzFtVcdpMDFnvZ6noMkCAwEAATANBgkqhkiG9w0BAQsFAAOCAUEAp0mN

/2Ml6tVC8Zi0bkXJ8j+bUxaxCUU1nV7htzWOqlAsQn1mVb7lbkLZgOc7RfD5CxdLspAVIVU1Gekp

/tSLjbdA3obSlBFmIm5yU4PGN9YjLRi5jbAAJNhJYThFB0YJu4M6tqX0nbxX6GphPeh2ruQ6WzeS

KwUf62gqd96WZeIwAKLoAZng4G9LZNITL7jUgl4OWq9OzZ+JYpe/rSz1tKWAg9r5U/AEkoZasfPo

3MLQlNCTh/WQm8jmtsyglct4k5SNI3ABhFcPfcR0PIhCjTVd7vlY8NcdaxSYYRzQgKZ7N8pdhvi3

NyPZmbu4OJXkc4Fupuyp2YxhGh0AtLKvdPRmybNZCmTRejgGbJeE6LjkcJ2zcunb+LxbyoxJ1DdU

K1tddzVPdH+QK8q3EKBNt0H3KwbRPk9qRmH4xuoX4XA=

—–END CERTIFICATE—–

Example code:

import javax.xml.transform.Transformer;

import javax.xml.transform.TransformerFactory;

import javax.xml.transform.dom.DOMSource;

import javax.xml.transform.stream.StreamResult;

import javax.xml.transform.stream.StreamSource;

import org.apache.xml.security.keys.KeyInfo;

import org.apache.xml.security.keys.content.X509Data;

import org.apache.xml.security.keys.content.x509.XMLX509Certificate;

import org.apache.xml.security.signature.XMLSignature;

public class Signer{

  public byte[] sign(VPOS root, PrivateKey prik, java.security.cert.X509Certificate[] crts) throws Exception{

    org.w3c.dom.Document dom = apis.marschalToDOM(root);

    // apis.normalizeDOM(dom); dom nomralization is very slow using instead

    // msg.setIdAttribute("messageId", true);

    Element vpos = dom.getDocumentElement();

    XMLSignature xmlsigAp = new XMLSignature(dom, null, "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256", "http://www.w3.org/TR/2001/REC-xml-c14n-20010315");

    Element sigel = xmlsigAp.getElement();

    vpos.appendChild(sigel);

    Element msg = (Element)vpos.getFirstChild();

    // setting id attribute instead of dom normalization

    msg.setIdAttribute("messageId", true);

    xmlsigAp.addDocument("#" + msg.getAttribute("messageId"), null, "http://www.w3.org/2001/04/xmlenc#sha256", null, null);

    for (int i = 0; crts != null && i < crts.length; i++){

      xmlsigAp.addKeyInfo(crts[i]);

    }

    xmlsigAp.sign(prik);

    ByteArrayOutputStream bos = new ByteArrayOutputStream(4096);

    TransformerFactory transfac = TransformerFactory.newInstance();

    Transformer trans = transfac.newTransformer();

    trans.setOutputProperty(OutputKeys.OMIT_XML_DECLARATION, "no");

    trans.setOutputProperty(OutputKeys.INDENT, "no");

    trans.setOutputProperty(OutputKeys.ENCODING, "utf-8");

    DOMSource source = new DOMSource(dom);

    trans.transform(source, new StreamResult(bos));

    return bos.toByteArray();

  }

}

Example sale request (assume there is no line breaks until end of <Message> part)

<VPOS xmlns="http://www.modirum.com/schemas/vposxmlapi41" xmlns:ns2="http://www.w3.org/2000/09/xmldsig#">
<Message messageId="M1560776270228" timeStamp="2019-06-17T15:57:50.228+03:00" version="4.1">
  <SaleRequest>
    <Authentication>
      <Mid>0000001</Mid>
    </Authentication>
    <OrderInfo>
      <OrderId>1560776235400</OrderId>
      <OrderDesc>Test</OrderDesc>
      <OrderAmount>1.25</OrderAmount>
      <Currency>EUR</Currency>
      <PayerEmail/>
    </OrderInfo>
    <PaymentInfo>
      <PayMethod>visa</PayMethod>
      <CardPan>4016000000002</CardPan>
      <CardExpDate>2206</CardExpDate>
      <CardCvv2>756</CardCvv2>
      <CardHolderName>John Smith</CardHolderName>
    </PaymentInfo>
  </SaleRequest>
</Message>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
  <ds:SignedInfo> 
    <ds:CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
    <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/> 
    <ds:Reference URI="#M1560776270228">
      <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
      <ds:DigestValue>82t/HCbRKUrAKVsA1tOpU8zXi3wIupTUeBndZ90VALM=</ds:DigestValue>
    </ds:Reference>
  </ds:SignedInfo>
  <ds:SignatureValue>DhADR21OEzIikjwgZh61pibBULtI0iRbkSEt6z2mdVGpQRgI3UFIepkYvTeNZv84cF2jM6JCrFbxdXMIR
  Q643rFXwOAnstv0QyRFPD4XCQDltSfoqDNfjAQE2wXmYWgHGJdI/0Vu12TJ64XzdEhb4E6t8yGfyYL
  6DdXZk4oBRZxBRqGBA6zxyDRdRvLq9V+LGIwZk4J7p6M+wZWDTb50/pOSU2wlP/s4IPtQvZQYWct
  9Huq/sFI+qwAG7na0L25zE9cB467lcaKmgGGLXFrRwDX6xAmoZOwFIW5x0CXbtM2X2j8vH53/Hfh1r
  dsWRxbOs7+ObLYvct/BA6KRbMxBPA==</ds:SignatureValue>
  <ds:KeyInfo>
  <ds:X509Data>
  <ds:X509Certificate>MIIDuzCCAqOgAwIBAgIJANh5ptk5BWu5MA0GCSqGSIb3DQEBCwUAMHQxCzAJBgNVB
  AYTAkVFMREwDwYDVQQIDAhNeSBTdGF0ZTEQMA4GA1UEBwwHbXkgQ2l0eTEVMBMGA1UE
  CgwMQ29tcGFueSBOYW1lMRAwDgYDVQQLDAc3NzExMjIzMRcwFQYDVQQDDA53d3cubXlzaXR
  lLmNvbTAeFw0xNzAzMjkxNzM3MDFaFw0yMTAzMjgxNzM3MDFaMHQxCzAJBgNVBAYTAkVFM
  REwDwYDVQQIDAhNeSBTdGF0ZTEQMA4GA1UEBwwHbXkgQ2l0eTEVMBMGA1UECgwMQ29tc
  GFueSBOYW1lMRAwDgYDVQQLDAc3NzExMjIzMRcwFQYDVQQDDA53d3cubXlzaXRlLmNvbTCC
  ASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBANpfsl3XqizYy2JxcdcaNqdDd8NLDChFGF
  VaLXb5KIUMxUGkHBkQZ2Yeik7lylIam0XF5q7seoZ9Jqrk2gjTWlt/848Wmy07iZKUgGPY473DNxbbI1
  4BCPPJwRCaA2vVRAAJSZew3MFlnaatx12R1GnF8c9pnH4Yhgx16YVjsbTIFewbQOr7eGL2SrIZiUA3c
  8WyoIR3APcfyp3lQrPjAoRiG6qEoFlmgYEFRBm3tf2mXB0yhmG2pskglOl1rk6D/I3GRKOJNCs4ye29K
  Xl0BDx0bGgVooB29oTT16q3QXpEjvqrJRTcHQ8oFUH+QhiG8VK8m15/prx8XhLLnpU4ym0CAwEAA
  aNQME4wHQYDVR0OBBYEFJaXNDk3UIJT7bjuedk13vmz62RjMB8GA1UdIwQYMBaAFJaXNDk3UI
  JT7bjuedk13vmz62RjMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAJx7UBdBddB
  bJ8sz/Fa3YvDlVR/GNTLp/haKC6G+FA97H5u2S7OGgXUnIX2T3M94QllhTykkzfr1zJeDZD+YrYyhAyp
  /ykHL0gk0tumHw8DN1BRmglRMc4QEXXHsx1HnMlcS0uE622M2+IQeDzDtLYpfXL36Dqoik0hIuNSjl
  xqlIX4kBweA83Xx9IGyhsMhXHSS0BcPVmup97PTAs81YGOu7vVgzyLBTHjabRktd0hVdm9+EJ/RMM
  FTW4XM+Ue2ekFx3uEX2B53ND6Mx5mtP/pibQ7/860FXUNdrHbcQCFufqhk7Ikr3+kv+Rqmh5DmrUbb
  lpmXFvm6iLc6uYZqIvE=</ds:X509Certificate>
  </ds:X509Data>
  </ds:KeyInfo>
</ds:Signature>
</VPOS>

Response signed by service provider (assume no line breaks until end of <Message> part)

<VPOS xmlns="http://www.modirum.com/schemas/vposxmlapi41" xmlns:ns2="http://www.w3.org/2000/09/xmldsig#">
<Message messageId="M1560776270228" timeStamp="2019-06-17T15:57:50.502+03:00" version="4.1">
    <SaleResponse>
        <OrderId>1560776235400</OrderId>
        <OrderAmount>1.25</OrderAmount>
        <Currency>EUR</Currency>
        <PaymentTotal>1.25</PaymentTotal>
        <Status>CAPTURED</Status>
        <TxId>927703821</TxId>
        <PaymentRef>104037</PaymentRef>
        <RiskScore>10</RiskScore>
        <Description>OK, CAPTURED response code 00</Description>
        <Attribute name="EXTACQUIRERID">014</Attribute>
    </SaleResponse>
</Message>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> 
    <ds:SignedInfo>
        <ds:CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/> 
        <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
        <ds:Reference URI="#M1560776270228">
            <ds:DigestMethodAlgorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
            <ds:DigestValue>6nt7AHK5fyrhVW/Mdp9Slx/NBHMfekjbfThFVBRKkt8=</ds:DigestValue>
        </ds:Reference>
    </ds:SignedInfo>
    <ds:SignatureValue>Wjb1yBQzPok9VKu9U37ua3i/OsqcMZQKAvyE6iOML43rteMgorpmwlOWQSQvLHqFQt
    s4HVxvMkruDufn7wuRfqmjDWLzgUqHpFTz+heOGDXhc88ovCaE7vFeYDJg+/isHjaO29ETe6+NH8oD
    vq4/no00mA/eHWqNB+vH51+jQCZfRI+tavz1iPAFLAF9Sl5IitaiuGXkEOoOxMbZ7FAb8GT++1MuZYD
    FgWLhZ/skR57b/LobPY5n5+AkEdqc86Dyk8/zOJC6RRS9TuJWoAIgJOaVNulSB6X/lsmfu7+GDDEynqx
    obZ0djEMwXhfLSfNlNHHqkePKxEhlXMFkEL5B1jGTnHs26yymy9JYq6TtwUq9XjEn2XnYl0Oa9hwCF
    IJ8a5p8u0nPJqtWNJKqDD1YH7FSEc7cBbM8SoTjXAyLZssZmBvJ+bba+FyIl5wTeD2RKtPenptu3uoyyL
    60c+ZeGs9+N3sfWh2jpztcSAj4xLQEre59UvFE478Kw78MfF0k</ds:SignatureValue>
    <ds:KeyInfo>
    <ds:X509Data>
    <ds:X509Certificate>MIIEXjCCAsYCAQEwDQYJKoZIhvcNAQELBQAwdTElMCMGA1UEA
    xMcQ2FyZGxpbmsgVUFUIFNpZ25pbmcgYW5kIENTRTENMAsGA1UECxMERUNPTTERMA8GA1U
    EChMIQ2FyZGxpbmsxDzANBgNVBAcTBkF0aGVuczEMMAoGA1UECBMDQVRIMQswCQYDVQQ
    GEwJHUjAeFw0xODA2MjEyMTAwMDBaFw0yNTA2MjIyMDU5NTlaMHUxJTAjBgNVBAMTHENhc
    mRsaW5rIFVBVCBTaWduaW5nIGFuZCBDU0UxDTALBgNVBAsTBEVDT00xETAPBgNVBAoTCEN
    hcmRsaW5rMQ8wDQYDVQQHEwZBdGhlbnMxDDAKBgNVBAgTA0FUSDELMAkGA1UEBhMCR1I
    wggGiMA0GCSqGSIb3DQEBAQUAA4IBjwAwggGKAoIBgQDlZIj4eMY2hU7ot4kkgB1e7xJniAe07ntR
    VwPZdJ1cxevLvSoQMvgd8070RrT7cPDXp6iJIl0RKBnCwZspwoO5evUngdfoAleyLSVUXljKp2G/e6Kt2
    2RMCLtYsqNv4qFW5nW8XwB88wvqziSMPu9Mo1gGhOxWpS4Viy3NvrtEVOWXvssx+ZLPolb3AW93
    w7BOfzEpt7LM3GwrSYZuPoPHcwdkBs0nF+htIEOq/2T7GDcZPNIUmllu4nQt6u7T1SJ0/TpdHta/p55xpt
    E7QLZlNdphIxvu4Zc9U7mwvlCN8MqMNQnQSFlqnBdOgtQ5gxfE8x/cSWOVLzTh6dWOc2o7aiAhk8sV
    opl7N4jeL4U4Nvp0GyDodoWgUJeweDookIb9DL2fgQeBLKn8ZFDPOyoBQSNr8AAm3p0bgTDY4XkT
    uav919LGgCjR5k389CW256zXCgsj5Dnn8gcTrf0mwziUbjlGt/UIy7CA7kmpELwna4NNo7Lt6laILqletJi1r
    lECAwEAATANBgkqhkiG9w0BAQsFAAOCAYEAVkOFbVwxj/pbnTH8Z2y/17P1yzv4H6vKB2RdG60
    CMSou0X/WNybBgaMSf6qJJs3osUC68qx27Q3pYp4i7onsTlNedhSsUVZVabRHXkjLxGLx9saZNiZ9turI
    yxzfC7VdeGaogvmcFPZAFgkGSFy4tAZz8fIkL7XI9pp5NTrjP9AL1ETVgwoHFKoeEKU1ewgQGRXpsM
    2sQnanMrTOgfVWz+qmaMmCcgeuQnYDPkZXX3jo456N0IDcGhJRmzkO8x0ge3DGyTc2mdS+38c61V
    EDd2TQHDHJuGsjCSVMjYh83JF7Ut3imFYhv3jgmHNkEDsp7XU81UMaV1nD0WzwNTbuMlyuvUQlt
    LtQ0lciDl+yT7zciHZr3JkL3am9lCtny/DROyw7pZnDCbWHaUKl4pV5UtwCIT/o5v7yo3av1z5o6Ufial+ke
    meyhcU7PtMXZ6mgW9Hcq4htX1BTl/LsTN/42XxvrdzystkmvJeSlrNLPbeASi8MC3j/xQdUjc6mWQ/t</ds:X509Certificate>
    </ds:X509Data>
    </ds:KeyInfo>
</ds:Signature>
</VPOS>

XML Requests is used for primary or secondary transactions. The term primary means all financial (Sales/Preauthorization) transactions, while the secondary ones are those that are directly related to an existing, previous transaction (eg refunds, cancellations, status request etc.).

All merchants can use VPOS XML Requests. Merchants with Direct integration (PCI DSS certifired) can consume XML VPOS requests for both groups of transactions (primary and secondary), whilst merchants with Redirect integration can use them only for secondary transactions.