- Home
- All APIs
- WPG guide
- Authentication
- 3DS with an external MPI
3DS with an external MPI
Use the external MPI to process
Prerequisite:
- Before using the external MPI with Worldpay, you need to be set up. For more information, contact your Relationship Manager.
- If you are using the
Split Authentication service , ensure that the<orderCode>
in the authorisation request is different to the one in the authenticate request.
We have ensured backwards compatibility with the
Authorisation Request - New External MPI
Submit the payment request including the below elements you have received from your approved authentication provider or the Worldpay Split Authentication service.
3DS1
<info3DSecure>
<threeDSVersion>1.0.2</threeDSVersion>
<xid>z9UKb06xLziZMOXBEmWSVA1kwG0=</xid>
<cavv>MAAAAAAAAAAAAAAAAAAAAAAAAAA=</cavv>
<eci>05</eci>
</info3DSecure>
<info3DSecure> <threeDSVersion>1.0.2</threeDSVersion> <xid>z9UKb06xLziZMOXBEmWSVA1kwG0=</xid> <cavv>MAAAAAAAAAAAAAAAAAAAAAAAAAA=</cavv> <eci>05</eci> </info3DSecure>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd" >
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
<submit>
<order orderCode="YOUR_ORDER_CODE">
<description>ORDER DESCRIPTION</description>
<amount value="100" currencyCode="EUR" exponent="2"/>
<orderContent><![CDATA[]]></orderContent>
<paymentDetails>
<CARD-SSL>
<cardNumber>4444333322221111</cardNumber>
<expiryDate>
<date month="06" year="2019"/>
</expiryDate>
<cardHolderName>AUTHORISED</cardHolderName>
<cvc>555</cvc>
<cardAddress>
<address>
<address1>Worldpay</address1>
<address2>270-289 The Science Park</address2>
<postalCode>CB4 0WE</postalCode>
<city>Cambridge</city>
<countryCode>GB</countryCode>
</address>
</cardAddress>
</CARD-SSL>
<info3DSecure>
<threeDSVersion>1.0.2</threeDSVersion>
<xid>z9UKb06xLziZMOXBEmWSVA1kwG0=</xid>
<cavv>MAAAAAAAAAAAAAAAAAAAAAAAAAA=</cavv>
<eci>05</eci>
</info3DSecure>
</paymentDetails>
</order>
</submit>
</paymentService>
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd" > <paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE"> <submit> <order orderCode="YOUR_ORDER_CODE"> <description>ORDER DESCRIPTION</description> <amount value="100" currencyCode="EUR" exponent="2"/> <orderContent><![CDATA[]]></orderContent> <paymentDetails> <CARD-SSL> <cardNumber>4444333322221111</cardNumber> <expiryDate> <date month="06" year="2019"/> </expiryDate> <cardHolderName>AUTHORISED</cardHolderName> <cvc>555</cvc> <cardAddress> <address> <address1>Worldpay</address1> <address2>270-289 The Science Park</address2> <postalCode>CB4 0WE</postalCode> <city>Cambridge</city> <countryCode>GB</countryCode> </address> </cardAddress> </CARD-SSL> <info3DSecure> <threeDSVersion>1.0.2</threeDSVersion> <xid>z9UKb06xLziZMOXBEmWSVA1kwG0=</xid> <cavv>MAAAAAAAAAAAAAAAAAAAAAAAAAA=</cavv> <eci>05</eci> </info3DSecure> </paymentDetails> </order> </submit> </paymentService>
3DS2
<info3DSecure>
<threeDSVersion>2.1.0</threeDSVersion>
<dsTransactionId>c5b808e7-1de1-4069-a17b-f70d3b3b1645</dsTransactionId>
<cavv>MAAAAAAAAAAAAAAAAAAAAAAAAAA=</cavv>
<eci>05</eci>
</info3DSecure>
<info3DSecure> <threeDSVersion>2.1.0</threeDSVersion> <dsTransactionId>c5b808e7-1de1-4069-a17b-f70d3b3b1645</dsTransactionId> <cavv>MAAAAAAAAAAAAAAAAAAAAAAAAAA=</cavv> <eci>05</eci> </info3DSecure>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
<submit>
<order orderCode="YOUR_ORDER_CODE">
<description>ORDER DESCRIPTION</description>
<amount value="100" currencyCode="EUR" exponent="2"/>
<orderContent><![CDATA[]]></orderContent>
<paymentDetails>
<CARD-SSL>
<cardNumber>4444333322221111</cardNumber>
<expiryDate>
<date month="06" year="2019"/>
</expiryDate>
<cardHolderName>AUTHORISED</cardHolderName>
<cvc>555</cvc>
<cardAddress>
<address>
<address1>Worldpay</address1>
<address2>270-289 The Science Park</address2>
<postalCode>CB4 0WE</postalCode>
<city>Cambridge</city>
<countryCode>GB</countryCode>
</address>
</cardAddress>
</CARD-SSL>
<info3DSecure>
<threeDSVersion>2.1.0</threeDSVersion>
<dsTransactionId>c5b808e7-1de1-4069-a17b-f70d3b3b1645</dsTransactionId>
<cavv>MAAAAAAAAAAAAAAAAAAAAAAAAAA=</cavv>
<eci>05</eci>
</info3DSecure>
</paymentDetails>
</order>
</submit>
</paymentService>
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd"> <paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE"> <submit> <order orderCode="YOUR_ORDER_CODE"> <description>ORDER DESCRIPTION</description> <amount value="100" currencyCode="EUR" exponent="2"/> <orderContent><![CDATA[]]></orderContent> <paymentDetails> <CARD-SSL> <cardNumber>4444333322221111</cardNumber> <expiryDate> <date month="06" year="2019"/> </expiryDate> <cardHolderName>AUTHORISED</cardHolderName> <cvc>555</cvc> <cardAddress> <address> <address1>Worldpay</address1> <address2>270-289 The Science Park</address2> <postalCode>CB4 0WE</postalCode> <city>Cambridge</city> <countryCode>GB</countryCode> </address> </cardAddress> </CARD-SSL> <info3DSecure> <threeDSVersion>2.1.0</threeDSVersion> <dsTransactionId>c5b808e7-1de1-4069-a17b-f70d3b3b1645</dsTransactionId> <cavv>MAAAAAAAAAAAAAAAAAAAAAAAAAA=</cavv> <eci>05</eci> </info3DSecure> </paymentDetails> </order> </submit> </paymentService>
XML Reference
The table below defines the data requirements for 3DS1 and 3DS2
Element | M/C/O | Length | Description |
---|---|---|---|
<threeDSVersion> | Conditional | 10 | This field contains the 3DS version used for authentication. Possible Values:
This must be provided for 3DS2, however we recommend you provide this for both 3DS1 and 3DS2. |
<xid> | Conditional | 28 | Transaction identifier resulting from authentication processing. Base64 encoded. For 3DS1, you must provide this for <eci> values of 05, 06, 01 and 02. |
<dsTransactionId> | Conditional | 36 | Unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction. RFC 4122 UUID standard. Best practice: You must provide this when 3DS2 was used. |
<cavv> | Conditional | 28 |
If this returned to you by your authentication provider, you must supply this. It is mandatory for <eci> values of 05, 06, 01 and 02. |
<eci> | Mandatory | 2 | Electronic Commerce Indicator (ECI). The ECI value is part of the two data elements that indicate the transaction was processed electronically. This should be passed in the authorisation request to the gateway. Possible Values:
|
External MPI examples
3DS1 - Visa
<info3DSecure>
<threeDSVersion>1.0.2</threeDSVersion>
<xid>ZFBBQWVqejBYY3NzU21SMXA5STE=</xid>
<cavv>AAABAWFlmQAAAABjRWWZEEFgFz8=</cavv>
<eci>05</eci>
</info3DSecure>
<info3DSecure> <threeDSVersion>1.0.2</threeDSVersion> <xid>ZFBBQWVqejBYY3NzU21SMXA5STE=</xid> <cavv>AAABAWFlmQAAAABjRWWZEEFgFz8=</cavv> <eci>05</eci> </info3DSecure>
<info3DSecure>
<threeDSVersion>1.0.2</threeDSVersion>
<xid>ZFBBQWVqejBYY3NzU21SMXA5STE=</xid>
<eci>07</eci>
</info3DSecure>
<info3DSecure> <threeDSVersion>1.0.2</threeDSVersion> <xid>ZFBBQWVqejBYY3NzU21SMXA5STE=</xid> <eci>07</eci> </info3DSecure>
<info3DSecure>
<threeDSVersion>1.0.2</threeDSVersion>
<xid>ZFBBQWVqejBYY3NzU21SMXA5STE=</xid>
<cavv>AAABAWFlmQAAAABjRWWZEEFgFz8=</cavv>
<eci>06</eci>
</info3DSecure>
<info3DSecure> <threeDSVersion>1.0.2</threeDSVersion> <xid>ZFBBQWVqejBYY3NzU21SMXA5STE=</xid> <cavv>AAABAWFlmQAAAABjRWWZEEFgFz8=</cavv> <eci>06</eci> </info3DSecure>
<info3DSecure>
<threeDSVersion>1.0.2</threeDSVersion>
<eci>06</eci>
</info3DSecure>
<info3DSecure> <threeDSVersion>1.0.2</threeDSVersion> <eci>06</eci> </info3DSecure>
3DS1 - Mastercard
<info3DSecure>
<threeDSVersion>1.0.2</threeDSVersion>
<xid>ZFBBQWVqejBYY3NzU21SMXA5STE=</xid>
<cavv>AAABAWFlmQAAAABjRWWZEEFgFz8=</cavv>
<eci>02</eci>
</info3DSecure>
<info3DSecure> <threeDSVersion>1.0.2</threeDSVersion> <xid>ZFBBQWVqejBYY3NzU21SMXA5STE=</xid> <cavv>AAABAWFlmQAAAABjRWWZEEFgFz8=</cavv> <eci>02</eci> </info3DSecure>
<info3DSecure>
<threeDSVersion>1.0.2</threeDSVersion>
<xid>ZFBBQWVqejBYY3NzU21SMXA5STE=</xid>
<eci>00</eci>
</info3DSecure>
<info3DSecure> <threeDSVersion>1.0.2</threeDSVersion> <xid>ZFBBQWVqejBYY3NzU21SMXA5STE=</xid> <eci>00</eci> </info3DSecure>
<info3DSecure>
<threeDSVersion>1.0.2</threeDSVersion>
<xid>ZFBBQWVqejBYY3NzU21SMXA5STE=</xid>
<cavv>AAABAWFlmQAAAABjRWWZEEFgFz8=</cavv>
<eci>01</eci>
</info3DSecure>
<info3DSecure> <threeDSVersion>1.0.2</threeDSVersion> <xid>ZFBBQWVqejBYY3NzU21SMXA5STE=</xid> <cavv>AAABAWFlmQAAAABjRWWZEEFgFz8=</cavv> <eci>01</eci> </info3DSecure>
<info3DSecure>
<threeDSVersion>1.0.2</threeDSVersion>
<eci>00</eci>
</info3DSecure>
<info3DSecure> <threeDSVersion>1.0.2</threeDSVersion> <eci>00</eci> </info3DSecure>
3DS2 - Visa
<info3DSecure>
<threeDSVersion>2.1.0</threeDSVersion>
<dsTransactionId>d75a496a-8d34-458e-80bf-d0c8b5e61701</dsTransactionId>
<cavv>Y2FyZGluYWxjb21tZXJjZWF1dGg=</cavv>
<eci>05</eci>
</info3DSecure>
<info3DSecure> <threeDSVersion>2.1.0</threeDSVersion> <dsTransactionId>d75a496a-8d34-458e-80bf-d0c8b5e61701</dsTransactionId> <cavv>Y2FyZGluYWxjb21tZXJjZWF1dGg=</cavv> <eci>05</eci> </info3DSecure>
<info3DSecure>
<threeDSVersion>2.1.0</threeDSVersion>
<dsTransactionId>d75a496a-8d34-458e-80bf-d0c8b5e61701</dsTransactionId>
<cavv>Y2FyZGluYWxjb21tZXJjZWF1dGg=</cavv>
<eci>06</eci>
</info3DSecure>
<info3DSecure> <threeDSVersion>2.1.0</threeDSVersion> <dsTransactionId>d75a496a-8d34-458e-80bf-d0c8b5e61701</dsTransactionId> <cavv>Y2FyZGluYWxjb21tZXJjZWF1dGg=</cavv> <eci>06</eci> </info3DSecure>
3DS2 - Mastercard
<info3DSecure>
<threeDSVersion>2.1.0</threeDSVersion>
<dsTransactionId>d75a496a-8d34-458e-80bf-d0c8b5e61701</dsTransactionId>
<cavv>Y2FyZGluYWxjb21tZXJjZWF1dGg=</cavv>
<eci>06</eci>
</info3DSecure>
<info3DSecure> <threeDSVersion>2.1.0</threeDSVersion> <dsTransactionId>d75a496a-8d34-458e-80bf-d0c8b5e61701</dsTransactionId> <cavv>Y2FyZGluYWxjb21tZXJjZWF1dGg=</cavv> <eci>06</eci> </info3DSecure>
<info3DSecure>
<threeDSVersion>2.1.0</threeDSVersion>
<dsTransactionId>d75a496a-8d34-458e-80bf-d0c8b5e61701</dsTransactionId>
<cavv>Y2FyZGluYWxjb21tZXJjZWF1dGg=</cavv>
<eci>01</eci>
</info3DSecure>
<info3DSecure> <threeDSVersion>2.1.0</threeDSVersion> <dsTransactionId>d75a496a-8d34-458e-80bf-d0c8b5e61701</dsTransactionId> <cavv>Y2FyZGluYWxjb21tZXJjZWF1dGg=</cavv> <eci>01</eci> </info3DSecure>
Errors
There are a number of errors you can receive when using the External MPI.
Error Code | Error Description | How to resolve |
---|---|---|
5 | cavv must be present for eci values '01', '02' or '05'. | These eci values apply to 3DS1. Ensure you submit a cavv for the right eci values. |
5 | cavv must be present for eci values '01', '02', '05' or '06'. | These eci values apply to 3DS2. Ensure you submit a cavv for the right eci values. |
5 | xid must be present for 3DS version 1. | Ensure you are supplying an xid when the <threeDSVersion> is 1.0.2. |
5 | cavv must be 28 digits in length. | Ensure you are supplying a cavv that is 28 digits in length. |
5 | xid must be 28 digits in length. | Ensure you are supplying an xid that is 28 digits in length. |
5 | dsTransactionId must be compliant with RFC 4122 UUID standard | Ensure the dsTransactionId conforms to the right standard. |
5 | cavv must be base64 encoded and 28 bytes in length. | Ensure you are providing a cavv in the right format. |
5 | xid must be base64 encoded and 28 bytes in length. | Ensure you are providing an xid in the right format. |
Legacy External MPI
We will continue to support the 'legacy' version of the External MPI:
<info3DSecure>
<xid>z9UKb06xLziZMOXBEmWSVA1kwG0=</xid>
<cavv>MAAAAAAAAAAAAAAAAAAAAAAAAAA=</cavv>
<eci>05</eci>
</info3DSecure>
<info3DSecure> <xid>z9UKb06xLziZMOXBEmWSVA1kwG0=</xid> <cavv>MAAAAAAAAAAAAAAAAAAAAAAAAAA=</cavv> <eci>05</eci> </info3DSecure>
However, if you want to start supporting 3DS2 (either using<dsTransactionId>
and <threeDSVersion>
for these requests.
Warning: With this version of the External MPI, you are able to provide empty elements, such as <cavv/>
. This is not supported in the new version of the External MPI. Instead, you must omit the element from the request.
You receive an XML payment response as per the standard