3-D Secure for Website Payments Pro

Important: Website Payments Pro is currently available in the UK only.

  • Existing integrations—PayPal continues to support merchants with existing integrations outside the UK.
  • New integrations—New integrations outside the UK must use PayPal Payments Pro, the replacement for Website Payments Pro.

Important: Strong Customer Authentication (SCA), a requirement of the second Payment Services Directive (PSD2), goes into effect on September 14, 2019. Card issuers are already beginning to implement 3-D Secure ahead of this deadline. If your checkout experience doesn't include 3-D Secure support, you will experience transaction failures on debit and credit card transactions when card issuers implement 3-D Secure. Note that PayPal-branded transactions and their funding may be subject to SCA, but PayPal handles the authentication request and processing for you.

Availability: An older version of these instructions, 3-D Secure with Cardinal Centinel, exist on this site but will be removed soon. For new UK integrations, use this topic and Cardinal Cruise™.

3-D Secure™ enables you to request the authentication of card holders by their card issuers. It reduces the likelihood of fraud when you use supported cards and improves transaction performance. Visa offers 3-D Secure as Visa Secure and MasterCard offers it as MasterCard Identity Check.

To pass 3-D Secure authentication data to PayPal for Payments Pro transactions, you must first obtain the data from the card's issuer. PayPal has an agreement with CardinalCommerce that enables Payments Pro merchants free access to CardinalCommerce's 3-D Secure technology, Cardinal Cruise™. The Cardinal Cruise Songbird Client interface authenticates transactions for Visa-, MasterCard-, and Maestro-branded cards.

This topic provides 3-D Secure integration guidance for:

  • Website Payments Pro merchants in the UK
  • Using the DoDirectPayment (NVP/SOAP) operation or Payflow

Integration steps

These integration steps assume you have an existing Direct Payments integration and are adding 3-D Secure to that integration using CardinalCommerce's Cardinal Cruise technology.

Tip: If your credit card payment integration is handled through a shopping cart partner, reach out to that partner and ask them to enable 3-D Secure for your integration rather than completing this integration yourself.

See What is PSD2? for a list of some of our cart technology parters who can implement a 3-D Secure authentication option for you.

Complete the following steps to integrate 3-D Secure into your existing Direct Payment integration:

1. Required Review 3-D Secure support and limitations for Website Payments Pro.
2. Required Register with CardinalCommerce.
3. Required Integrate with Cardinal Cruise.
4. Required Test your Cardinal integration with CardinalCommerce's test procedures.
5. Required Complete Direct Payment integration with additional 3-D Secure fields.
6. Required Test your entire direct payment integration in PayPal's sandbox.
7. Optional Refer to the supplemental documentation:
3-D Secure Reference
Frequently Asked Questions (FAQs)

1. Review 3-D Secure support and limitations for Website Payments Pro

The following support and limitations apply to the Website Payments Pro 3-D Secure integration procedure:

  • Support
    • UK-based Website Payments Pro merchants
    • Debit and credit cards processed with the DoDirectPayment API request
    • Implements 3-D Secure 1.0 and 2.0
  • Limitations
    • Participation in only the Visa Secure and MasterCard Identity Check programs
    • While a US or Canadian merchant can implement 3-D Secure, the authentication data is ignored by PayPal. This information applies only to 3-D Secure for UK merchants implementing Direct Payment.

2. Register with CardinalCommerce and install software

Before you can use Cardinal Cruise to obtain cardholder authentication, you must register with CardinalCommerce. After you have registered, CardinalCommerce acknowledges your 3-D Secure registration by sending you an email and welcome pack, which includes information about next steps and links for downloading their documentation and software.

3. Integrate Cardinal Cruise Standard

A Cardinal Cruise integration consists of a JavaScript file called Songbird.js, JSON Web Tokens (JWT) for client authentication, JSON objects to pass from your merchant front-end environment to Cardinal, and event handlers to know when events have completed.

Refer to the CardinalCommerce documentation to integrate either Cardinal Cruise Standard or Hybrid, depending on which fits your needs:

Note: CardinalCommerce is available for an integration meeting and to support you with your Cardinal Cruise integration requirements.

4. Test your integration using CardinalCommerce's test procedures

You can't use PayPal's sandbox for testing your Cardinal Cruise integration. You must use CardinalCommerce's test procedures.

5. Complete Direct Payment integration using 3-D Secure fields

Once the cardholder is authenticated, execute the direct payment transaction request and include the following 3-D Secure fields:

Note: If you are using Payflow rather than DoDirectPayment, refer to Payflow 3-D Secure with 3rd-Party Merchant Plug-ins for integration instructions.

3-D Secure 1.0

NVP Field SOAP Field Description
VERSION Version Set to 59.0 or higher.
AUTHSTATUS3DS AuthStatus3ds Optional field. Set this to the returned PAResStatus value.
MPIVENDOR3DS MpiVendor3ds Optional field. Set this to Enrolled.
CAVV Cavv Set to the returned Cavv value.
ECI3DS Eci3ds Set to the returned EciFlag value.
XID Xid Set to the returned Xid value.

DoDirectPayment example for 3-D Secure 1.0

The following examples show the additional fields required for 3-D Secure 1.0 transactions. Refer to DoDirectPayment (NVP/SOAP) for all required fields.

NVP 3-D 1.0 fields example
ECI3DS=5&XID=2jHIHesJqwddrITFPys8C57vZ1I&MPIVENDOR3DS=Y&AUTHSTATUS3DS=Y&VERSION=59.0
SOAP 3-D 1.0 fields example
<Version>59.0</Version>
.
.
.
<ThreeDSecureRequest>
    <MpiVendor3ds>Y</MpiVendor3ds>
    <AuthStatus3ds>Y</AuthStatus3ds>
    <Cavv>jMKEKlqlJGiJARAbxMDZ5+fnFeg=</Cavv>
    <Eci3ds>02</Eci3ds>
    <Xid>TTVmdlFxbERYVXo5R1hrVUY5bjY=</Xid>
</ThreeDSecureRequest>

3-D Secure 2.0

The 3-D Secure 2.0 implementation is similar to the 1.0 implementation with the following changes:

  • The value in the VERSION field
  • 2.0-specific fields, DSTRANSACTIONID and THREEDSVERSION
NVP Field SOAP Field Description
VERSION Version For 3-D Secure 2.0, set this field to 214.
AUTHSTATUS3DS AuthStatus3ds Optional field. Set this to the returned PAResStatus value.
MPIVENDOR3DS MpiVendor3ds Optional field. Set this to Enrolled.
CAVV Cavv Set to the returned Cavv value.
ECI3DS Eci3ds Set to the returned EciFlag value.
XID Xid Set to the returned Xid value.
DSTRANSACTIONID DSTransactionId New field for 3-D Secure 2.0. Unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction.

Note: Required for Mastercard Identity Check transaction in Authorization. Available only in EMV 3DS (3DS 2.0) transactions.
THREEDSVERSION ThreeDSVersion New field for 3-D Secure 2.0. This field contains the 3DS version that was used to process the transaction.
Possible values:
  • 1.0.2
  • 2.1.0
  • 2.2.0
Note: Required for Mastercard Identity Check transaction in Authorization.
DoDirectPayment examples for 3-D Secure 2.0

The following examples show the additional fields required for 3-D Secure 2.0 transactions.

NVP 3-D 2.0 fields example
ECI3DS=5&XID=2jHIHesJqwddrITFPys8C57vZ1I&MPIVENDOR3DS=Y&AUTHSTATUS3DS=Y&THREEDSVERSION=2.1.0&DSTRANSACTIONID=f38e6948-5388-41a6-bca4-b49723c19437&VERSION=214.0
SOAP 3-D 2.0 fields example
<Version>214.0</Version>
.
.
.
<ThreeDSecureRequest>
    <MpiVendor3ds>Y</MpiVendor3ds>
    <AuthStatus3ds>Y</AuthStatus3ds>
    <Cavv>jMKEKlqlJGiJARAbxMDZ5+fnFeg=</Cavv>
    <Eci3ds>02</Eci3ds>
    <Xid>TTVmdlFxbERYVXo5R1hrVUY5bjY=</Xid>
    <ThreeDSVersion>2.1.0</ThreeDSVersion>
    <DSTransactionId>f38e6948-5388-41a6-bca4-b49723c19437</DSTransactionId>
</ThreeDSecureRequest>
3-D Secure API errors

You might encounter the following API errors related to 3-D Secure authentication:

  • If you execute a direct payment transaction for a Maestro card without authenticating using 3-D Secure, PayPal returns ACK=Failure with error code 12000 and PayPal will not accept the transaction.
  • If you execute a direct payment transaction for a card that requires 3-D Secure authentication and the 3-D Secure values are missing, invalid, or incomplete, the issuing bank declines the transaction and PayPal returns error code 12002.

Reference Transactions and Recurring Payments

If you complete reference transactions or recurring payments, you might need to update your existing integrations for account for the SCA requirements. Refer to the following topics for more information:

6. Test your entire direct payment integration in PayPal's sandbox

Refer to Test your Direct Payment integration for information about testing your entire direct payment integration in PayPal's sandbox.

Note: If you are using Payflow rather than DoDirectPayment, refer to the Payflow Developer Guide for testing instructions.

3-D Secure reference

See the Cardinal documentation for up-to-date and complete reference information.

3-D Secure frequently asked questions

What is Strong Customer Authentication (SCA)?

Strong Customer Authentication (SCA) is a requirement from the second Payment Services Directive (PSD2). The PSD2 text introduces strict security requirements for the initiation of electronic payments in order to reduce the risk of fraud. These requirements include strong customer authentication, which is an authentication process that validates the identity of the user of a payment service, which will be compulsory on the September 14, 2019. Many card issuers are already beginning to implement SCA ahead of this deadline. If your checkout experience doesn't include 3-D Secure support, you will experience transaction failures on debit and credit card transactions when card issuers implement 3-D Secure.

For more information about SCA, see Strong Customer Authentication and What is PSD2?.

Why do I need to enable 3-D Secure for my Website Payments Pro integration?

Strong Customer Authentication (SCA) goes into effect on September 14, 2019. Using 3-D Secure ensures your checkout experience meets the requirement for SCA. Card issuers are already beginning to implement 3-D Secure ahead of this deadline. If your checkout experience doesn't include 3-D Secure support, you will experience transaction failures on debit and credit card transactions when card issuers implement 3-D Secure.

Note: PayPal-branded transactions and their funding may be subject to SCA, but PayPal handles the authentication request and processing for you.

Who is CardinalCommerce?

CardinalCommerce is a global leader in authenticating digital transactions and operates as a wholly-owned subsidiary of Visa. PayPal has an agreement with CardinalCommerce that enables Payments Pro merchants free access to Cardinal's 3-D Secure technology, Cardinal Cruise. The Cardinal Cruise Songbird Client interface authenticates transactions for Visa-, MasterCard-, and Maestro-branded cards.

Do credit card payment processors, other than PayPal, require 3-D Secure?

Yes. PSD2 and SCA impacts all payment providers in the European Economic Area (EEA).

Is there a fee for 3-D Secure?

No. PayPal has an agreement with CardinalCommerce that enables Payments Pro merchants free access to Cardinal's 3-D Secure technology, Cardinal Cruise.

Who can I contact if I have a technical question about a 3-D Secure integration?

Contact CardinalCommerce:

My integration is through a cart partner and 3-D Secure is available. How should I enable 3-D Secure?

Reach out to your cart partner and ask them to enable 3-D Secure for your integration.

My integration is through a cart partner and 3-D Secure is NOT available. What can I do?

You can enable 3-D Secure through CardinalCommerce to exist parallel to your cart integration. When you register for CardinalCommerce, select your cart on the registration page. If your cart is not listed on the registration page, select Custom Built Cart.

I cannot locate my transaction credentials from CardinalCommerce. How can I find them?

CardinalCommerce provides your credentials when you register with them. Make sure you whitelist the following email address: paypal3DSUKboarding@cardinalcommerce.com. Whitelisting an email address marks the address as a safe sender and allows emails from that address to pass through spam filters and into your inbox.

If you didn't proactively whitelist the email address, check your junk or spam email folder for the email with your credentials. If your credentials aren't in the junk/spam folder, email paypalUK@cardinalcommerce.com and ask them to regenerate them for you.

Why did I receive a message that I'm already registered with CardinalCommerce?

If you try to register with CardinalCommerce and receive a message that you're already enrolled, you might need to reset your password or request your cart credentials be re-sent to you.

Message: "It appears that you are already enrolled. If you need assistance with accessing your account, please try again or contact us at paypaluk@cardinalcommerce.com."

Who can I contact if 3-D Secure is no longer working in my cart?

Email paypalUK@cardinalcommerce.com.

Feedback