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>

3DS2

Copied!
<info3DSecure>
  <threeDSVersion>2.1.0</threeDSVersion>
  <dsTransactionId>c5b808e7-1de1-4069-a17b-f70d3b3b1645</dsTransactionId>
  <cavv>MAAAAAAAAAAAAAAAAAAAAAAAAAA=</cavv>
  <eci>05</eci>
</info3DSecure>

XML Reference

The table below defines the data requirements for 3DS1 and 3DS2

ElementM/C/OLengthDescription
<threeDSVersion>Conditional10This 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>Conditional28Transaction identifier resulting from authentication processing. Base64 encoded.

For 3DS1, you must provide this for <eci> values of 05, 06, 01 and 02.

<dsTransactionId>Conditional36Unique 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>Conditional28
  • 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>Mandatory2Electronic 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>
  <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>
  <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>
  <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>
  <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>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>06</eci>
</info3DSecure>

Errors

There are a number of errors you can receive when using the External MPI.

Error CodeError DescriptionHow to resolve
5cavv 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.
5cavv 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.
5xid must be present for 3DS version 1.Ensure you are supplying an xid when the <threeDSVersion> is 1.0.2.
5cavv must be 28 digits in length.Ensure you are supplying a cavv that is 28 digits in length.
5xid must be 28 digits in length.Ensure you are supplying an xid that is 28 digits in length.
5dsTransactionId must be compliant with RFC 4122 UUID standardEnsure the dsTransactionId conforms to the right standard.
5cavv must be base64 encoded and 28 bytes in length.Ensure you are providing a cavv in the right format.
5xid 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>

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.