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.

Braintree recurring billing subscriptions

If you use Braintree's recurring billing, follow the steps below to apply 3D Secure to subscriptions.

  1. Generate a payment method nonce out of a vaulted payment method token
  2. Verify that nonce using 3D Secure in your client. Successful results will have a new payment method nonce that is enriched with 3D Secure data.
  3. Use the generated 3D Secure enriched nonce in the Subscription.create() call.

Sometimes, you will need to re-establish SCA on an existing subscription, for example, if the price of the subscription has increased or the subscription will be updated with a new payment method. To do this:

  1. Generate a payment method nonce out of a vaulted payment method token
  2. Verify that nonce using 3D Secure in your client. Successful results will have a new payment method nonce that is enriched with 3D Secure data.
  3. Use the generated 3D Secure enriched nonce in the Subscription.update() call.

Other recurring transactions

For other types of recurring transactions that don't involve Braintree's recurring billing, the recommended flow for recurring billing would be to request a cardholder challenge in order to establish Strong Customer Authentication (SCA) when the card is first authorized as part of storing it within the Braintree vault. This can be with a verification, or the first transaction of a recurring billing event. By applying 3D Secure to the first transaction or verification, you signal to the card issuer that you have established a mandate between you and your customer to charge their payment method for subsequent recurring payments as detailed in your terms and conditions. Such subsequent transactions are out of scope from PSD2 SCA requirements.

Establishing SCA on verifications will be useful for scenarios where the cardholder will not be present when the charge is issued, and the amount isn’t known when the payment method is stored. For example, if you have a metered billing flow and invoice customers at the end of a month based on their usage, you can use 3D Secure on your initial card verification to establish a mandate to create future merchant initiatied transactions (MIT) without requiring 3D Secure authentication.

For subsequent transactions from that payment method, use the recurring value in the transaction_source parameter of the Transaction.Sale() API call.

Other merchant initiated transactions (MIT)

Other MIT transactions will be processed much the same way that recurring transactions would be. You would again request a cardholder challenge to establish SCA when the card is first authorized, establishing a mandate between you and your customer.

For subsequent transactions from that payment method, which would be outside of the scope of PSD2 SCA, use the unscheduled value in the transaction_source parameter of the Transaction.Sale() API call.

Requesting a cardholder challenge

To override the default behavior of 3DS 2 and request the cardholder's bank to issue an authentication challenge, pass challengeRequested: true on the verifyCard() call.

Exceptions for already-stored payment methods

Exceptions would apply for recurring transactions using a payment method that has been vaulted prior to September 14, 2019. Recurring transactions from these payment methods will be considered outside of the scope of PSD2 SCA as long as the payment method was successfully charged at least once prior to September 14, 2019.

For any vaulted payment methods not successfuly charged prior to this date, the first recurring transaction attempt will result in a 2099 - Cardholder Authentication Required soft decline code. Some issuers may not yet support this decline code, and will instead return other soft decline codes. In this case, the cardholder must perform 3D Secure authentication in order to process the transaction.

Next Page: Testing and Go Live →