Contents

Using your own MPI

 

The merchant plug-in (MPI) is a software module that is involved in part of the 3-D Secure process. The MPI identifies the customer’s card details and contacts the card issuer to determine if the card is enrolled in a 3-D Secure scheme. If enrolled, the MPI returns the address of the card issuer’s Access Control Server (ACS). The merchant redirects the customer’s browser to the ACS to verify their identity. This process is explained later in this document.

Secure Trading provides access to an MPI implementation that can be utilised by merchants, and our JavaScript library handles this during the default process as described in the main body of this document. However, if you already have your own MPI configured as part of your solution, please follow the alternative process described below:

 


 

Requirements

Important: If you use your own MPI, it is your responsibility to ensure your system follows the 3-D Secure specification and keeps up to date with any amendments issued by Visa and Mastercard. You must also provide Secure Trading with valid, unaltered and verified values for each 3-D Secure field specified below.

Warning
Failure to follow the specification outlined below may result in forfeiting any liability shift.

If you do not have values for specific fields listed in this section, you must NOT submit the fields in question in any requests to Secure Trading.

 


 

Handling enrolled cards

After establishing the card is enrolled in the 3-D Secure scheme and the customer has been authenticated successfully, your system will need to construct and submit an AUTH request to complete the payment.

The specification of the request largely follows that of a standard AUTH, with additional fields required for 3-D Secure, as shown in the example below.

 

Example

Info
The following example assumes you have obtained the necessary PCI certification to process and submit sensitive cardholder data in the request. Alternatively, you can submit the cachetoken value in the request.

{"alias":"[email protected]","version":"1.00","request":[{"orderreference":"order.ref","sitereference":"test_site12345","requesttypedescription":"AUTH","accounttypedescription":"ECOM","billingpostcode":"TE45 6ST","billingpremise":"789","paymenttypedescription":"MASTERCARD","expirydate":"10\/2031","pan":"5100000000000511","securitycode":"123","baseamount":"100","currencyiso3a":"GBP","cavv":"Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=","eci":"05","xid":"WElEWElEWElEWElEWElEWElEWEk=","enrolled":"Y","status":"Y","threedversion":"2.2.0","threeddirectorytransactionreference":"f00e1111-0011-00a6-ab00-a00000a00000"}]}

 

Field specification

Field Type Length Required Comment
cavv an Max 32 Conditional The unique Cardholder Authentication Verification Value (CAVV) associated with the transaction.

Always submit this value if it is available.

eci an Max 2 Conditional The ECI (E-Commerce Indicator) security level associated with the transaction.

Always submit this value if it is available.

xid an Max 255 Conditional The unique identifier for the transaction, assigned by your MPI (Merchant Plug-In).

Always submit this value if it is available.

enrolled an 1 Yes Submit ‘Y’ to indicate that card is enrolled. See below for information on handling not-enrolled cards.
status an 1 Yes Indicates whether or not the customer was authenticated on the card issuer’s ACS:

  • ‘Y’ – Customer authenticated.
  • ‘A’ – An authentication attempt occurred but could not be completed.
  • ‘U’ – Unable to perform authentication.
threedversion n 6 Conditional Version of 3-D Secure used to authenticate the payment. (e.g. “2.2.0”)

Always submit this value if it is available.

threeddirectorytransactionreference an Max 48 Conditional Reference that uniquely identifies the transaction with your MPI provider.

Always submit this value if it is available.

 

Warning
If status is ‘N’, this indicates the customer was not authenticated.

We strongly recommend against proceeding with the transaction.

 

You can continue with the payment, but the liability shift will be forfeited.

To do so, process an AUTH request manually.

 


 

Handling unenrolled cards (or if enrolment is “U” – Unknown)

Warning
If both your business and the cardholder’s bank are based within the European Economic Area (EEA) or the UK, your implementation must be compliant with the Revised Directive on Payment Services (PSD2).

 

PSD2 requires online card payments to be processed with 3-D Secure. If a card is not enrolled, the recommended approach would be to stop the transaction and offer the customer alternative means of payment.

 

If you have considered the legal implications covered above and are allowed to proceed, your system will need to construct and manually submit an AUTH request to complete the payment with an unenrolled card.

The specification of the request largely follows that of a standard AUTH, with additional fields required for 3-D Secure (as shown in the example below).

 

Example

Info
The following example assumes you have obtained the necessary PCI certification to process and submit sensitive cardholder data in the request. Alternatively, you can submit the cachetoken value in the request.

{"alias":"[email protected]","version":"1.00","request":[{"orderreference":"order.ref","sitereference":"test_site12345","requesttypedescription":"AUTH","accounttypedescription":"ECOM","billingpostcode":"TE45 6ST","billingpremise":"789","paymenttypedescription":"VISA","expirydate":"10\/2031","pan":"4111110000000211","securitycode":"123","baseamount":"100","currencyiso3a":"GBP","xid":"WElEWElEWElEWElEWElEWElEWEk=","enrolled":"N","threedversion":"2.2.0","threeddirectorytransactionreference":"f00e1111-0011-00a6-ab00-a00000a00000"}]}

 

Field specification

Field Type Length Required Comment
xid an Max 255 Conditional The unique identifier for the transaction, assigned by your MPI (Merchant Plug-In).

Always submit this value if it is available.

enrolled an 1 Yes Submit ‘N’ to indicate that card is not enrolled, or ‘U’ to indicate enrolment is unknown.
threedversion n 6 Conditional Version of 3-D Secure used to authenticate the payment. (e.g. “2.2.0”)

Always submit this value if it is available.

threeddirectorytransactionreference an Max 48 Conditional Reference that uniquely identifies the transaction with your MPI provider.

Always submit this value if it is available.