note

We have upgraded our 3D Secure integration in preparation for 3DS 2 and PSD2 Strong Consumer Authentication (SCA) compliance requirements in 2019.

This guide shows our integration for 3DS 2.

PSD2 Strong Customer Authentication (SCA) exemptions

Merchants can request an exemption from the SCA requirement for certain transactions. Exemptions are granted completely at the discretion of the issuer, and are never guaranteed. If an exemption is requested, and then granted by the issuer, authentication will not be required. However, in this case, the liability remains with the merchant and is not shifted to the issuer.

Braintree's client SDKs provide the ability to request an exemption for a given authentication. If you request an exemption, Braintree will automatically request the most appropriate exemption from the issuer.

Please note that issuers are currently upgrading their systems to support 3DS 2 as well as PSD2 SCA exemptions; many issuers may not support some or all exemptions until well into 2020.

For more information on exemptions, please read our blog on PSD2 SCA exemptions.

Client-side implementation

To request an exemption, call exemptionRequested(true) on the ThreeDSecureRequest object.

Server-side implementation

If you perform a 3D Secure authentication, the exemption request along with any exemption granted by the issuer will automatically be applied to the associated transaction; no exemption information is then required in the Transaction.sale() call.

In the future we will expand the options to allow you to specify the particular exemption you are requesting. This will be primarily useful for Forward API merchants.

Using your own 3D Secure MPI provider

If you perform a 3D Secure authentication with your own MPI provider and receive an SCA exemption from the issuer via 3D Secure, you'll need to specify which exemption was obtained in the Transaction.sale() call.

Specifying exemptions using your own 3D Secure MPI provider is in limited release. Contact us to request access to the release of this feature.

Authentication Insight

availability

Authentication Insight is currently available in the Java server SDK for vaulted payment methods.

Support for other server SDKs, as well as client SDKs and support for non-vaulted payment methods, is currently under development.

Authentication Insight provides you with more details about the regulatory environment and applicable customer authentication regulation for a potential transaction. This empowers you to make an informed decision whether to perform 3D Secure authentication.

When you have a customer's payment method stored in your vault, you can request it on the server-side via the Java server SDK.

You can use the regulation environment information contained in the Authentication Insight to make a decision about whether to perform a 3D Secure verification, or continue without a verification. If you choose to perform a 3D Secure verification, proceed as usual using the payment method nonce.

The regulation environment field currently has three possible values:

Regulation Environment Description
psd2 The impending transaction (when using the provided payment method nonce and merchant account) is believed to be within scope of PSD2 SCA regulations, and requires 3D Secure authentication.
unregulated The impending transaction is not believed to be within scope of any SCA regulations, PSD2 or otherwise.
unavailable The impending transaction’s SCA regulation environment could not be determined.

As global regulations evolve, these values will continue to be updated.

To retrieve the Authentication Insight for a nonce, on the PaymentMethodNonceRequest, set the authenticationInsight boolean option to true and specify your merchantAccountId.

Java
PaymentMethodNonceRequest createRequest = new PaymentMethodNonceRequest()
.paymentMethodToken(PAYMENT_METHOD_TOKEN)
.merchantAccountId(MERCHANT_ACCOUNT_ID)
.authenticationInsight(new Boolean(true));

Result<PaymentMethodNonce> result = gateway.paymentMethodNonce().create(createRequest);

if (result.isSuccess()) {
  PaymentMethodNonce nonce = result.getTarget();
  AuthenticationInsight authenticationInsight = 
    nonce.getAuthenticationInsight();
  String customerAuthenticationRegulationEnvironment =   
    authenticationInsight.getRegulationEnvironment();
}

Access the AuthenticationInsight object on the nonce by calling nonce.getAuthenticationInsight(); access the regulation environment value by calling getRegulationEnvironment() on the AuthenticationInsight object.

Testing

Currently, we have test cards available that can return the various regulation environment values when authentication insight is requested on tokenization, depending on the merchant account that is specified:

Test Value Card Information Regulation Environment Value
4012000033330620 country of issuance = "USA" unregulated
4023490000000008 country of issuance = "IRL"
  • psd2 if using a merchant account acquired in the EEA
  • unregulated if using a merchant account acquired outside the EEA
  • unavailable if using a merchant account where acquirer country is unknown or has not been specified