3DS with an external MPI

Use the external MPI to processdirect XML requestswith additional authentication data which you have received either through an approved MPI provider or Worldpay'sSplit Authentication service.

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 theSplit 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'legacy' External MPI, but you are not able to use it to process 3DS2 transactions. To support 3DS2, you must use the 'new' External MPI.

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

Copied!

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

Copied!

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

Copied!

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

Copied!

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd"&gt;
<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"&gt; <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: 1.0.2 2.1.0 2.2.0 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	Cardholder Authentication Verification Value (CAVV) Authentication Verification Value (AVV) Universal Cardholder Authentication Field (UCAF) Base64 encoded. 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: 02 or 05 - Fully Authenticated Transaction 01 or 06 - Attempted Authentication Transaction 00 or 07 - Non 3-D Secure Transaction Mastercard - 02, 01, 00 Visa - 05, 06, 07 Amex - 05, 06, 07 JCB - 05, 06, 07 Diners - 05, 06, 07

External MPI examples

3DS1 - Visa

Copied!

<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

Copied!

<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

Copied!

<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

Copied!

<info3DSecure>
  <threeDSVersion>2.1.0</threeDSVersion>
  <dsTransactionId>d75a496a-8d34-458e-80bf-d0c8b5e61701</dsTransactionId>
  <cavv>Y2FyZGluYWxjb21tZXJjZWF1dGg=</cavv>
  <eci>02</eci>
</info3DSecure>

<info3DSecure> <threeDSVersion>2.1.0</threeDSVersion> <dsTransactionId>d75a496a-8d34-458e-80bf-d0c8b5e61701</dsTransactionId> <cavv>Y2FyZGluYWxjb21tZXJjZWF1dGg=</cavv> <eci>02</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>

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:

Copied!

<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 usingSplit Authenticationor your own third party authentication provider), you must upgrade to the XML above. This is because you must provide the <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 standarddirect integration.

3DS with an external MPI

Authorisation Request - New External MPI

3DS1

3DS2

XML Reference

External MPI examples

3DS1 - Visa

3DS1 - Mastercard

3DS2 - Visa

3DS2 - Mastercard

Errors

Legacy External MPI

​