3D Secure

Applying 3DS to Transactions and Verificationsanchor

Table of Contentsanchor

Create a transactionanchor

Using 3D Secure upgraded single-use-tokenanchor

To create a 3D Secure transaction, make a server-side sale call using the payment method single-use-token you received from your client when you verified the credit card on the client side.

Collect device data from the client and include the device_data_from_the_client in the transaction.

  1. Python
result = gateway.transaction.sale({
    "amount": "10.00",
    "payment_method_nonce": nonce_from_the_client,
    "device_data": device_data_from_the_client,
    "options": {
      "submit_for_settlement": True
    }
})
important

3D Secure information is lost when a 3D Secured payment_method_nonce is used in a Customer.create() or PaymentMethod.create() call without a verify_card flag.

Using 3DS authentication IDanchor

To create a 3D Secure transaction using an authentication ID, make a server-side sale call using the authentication ID you received from your client when you verified the credit card on the client side. You can use a payment method token instead of a payment method single-use-token if you provide the 3D Secure authentication via an authentication ID.

  1. Python
result = gateway.transaction.sale({
    "amount": "10.00",
    "payment_method_token": token,
    "payment_method_nonce": cvv_only_nonce,
    "three_d_secure_authentication_id": authentication_id,
    "device_data": device_data_from_the_client,
    "options": {
      "submit_for_settlement": True
    }
})

If you want to use a CVV-only nonce when creating a transaction with 3D Secure, you will need to pass a 3D Secure Authentication ID together with the CVV-only nonce.

Create a verificationanchor

Create a new customer with a payment methodanchor

Make a server-side call using the 3D Secure upgraded payment_method_nonce you received from your client when you verified the credit card on the client side as shown in the customer guide .

As an alternative to passing the 3D Secure upgraded single-use-token, you can pass a three_d_secure_authentication_id using the authentication ID you received from your client when you verified the credit card on the client side. You can use a payment method token instead of a payment method single-use-token if you provide a three_d_secure_authentication_id.

Create a new payment methodanchor

Make a server-side call using the payment method single-use-token you received from your client when you verified the credit card on the client side as shown in the payment method guide .

As an alternative to passing the 3D Secure upgraded single-use-token, you can pass a three_d_secure_authentication_id using the authentication ID you received from your client when you verified the credit card on the client side. You can use a payment method token instead of a payment method single-use-token if you provide a three_d_secure_authentication_id.

Requiring 3D Secureanchor

We expose additional information about the authentication request that you can use for more advanced UI flows or risk assessment. You should be aware that making such assessments may result in accepting the liability for fraudulent transactions.

You can pass a parameter called required with the transaction,to specify whether or not you require 3D Secure authentication to have succeeded on a transaction. When you create a transaction with a 3D Secure enriched single-use-token, the options.three_d_secure.required parameter defaults to true. This implies that all transactions without a successful 3D Secure authentication will be rejected. If 3D Secure is not present, the required parameter defaults to false, which means that transactions will not be rejected based on 3D Secure.

We strongly recommend you allow this parameter to default to true, as it helps protect against malicious users tampering with your front-end code and bypassing 3D Secure completely. That being said, you do have the option of determining your own level of risk and pushing the transaction through regardless of its 3D Secure status by setting required to false on a per-transaction basis.

important

If you pass required as true on transactions that do not go through 3D Secure, those transactions will be gateway rejected.

3DS Status codesanchor

Below are the possible 3D secure statuses, along with their expected 3D Secure liability shift and enrolled values . This table also shows whether a transaction will be rejected by the PayPal Braintree gateway when options.three_d_secure.required is set to true when creating a transaction, or when creating or updating a subscription.

Status Liability Shift Possible Liability Shifted Reject if 3DS is required Enrolled Value
authenticate_attempt_successful
The associated card brand authenticated this 3D Secure transaction using its Attempts server because the card issuer's authentication server was unavailable.
true true No Y
authenticate_error
An error occurred within the 3D Secure authentication system; have the customer attempt the transaction again. Contact our Support team if most attempted 3D Secure transactions receive this error message.
true false Yes Y
authenticate_failed
The customer entered an incorrect 3D Secure password or they took too long to enter in a password value and the 3D Secure authentication timed out. Have the customer attempt the transaction again.
true false Yes Y
authenticate_successful
The transaction was successfully authenticated with 3D Secure.
true true No Y
authenticate_unable_to_authenticate
A downstream error occurred with the card-issuing bank that caused the 3D Secure authentication to fail. Have the customer attempt the transaction again.
true false Yes Y
authentication_unavailable
The card network is unavailable to verify the customer's card using 3D Secure. Your PayPal Braintree gateway may not be set up to accept the customer’s provided card type; 3D Secure transactions on this card type will be unavailable until the setup process is complete. If you have just enabled 3D Secure, the setup process for MasterCard can take 2-3 business days and American Express can take up to 7 business days. If you continue to see this status for all 3D Secure transactions for a particular card type after the setup process is complete, please Contact our Support team. This status could also indicate the 3D Secure authentication timed out; if you believe this to be the case, have the customer attempt the transaction again.
false false No U
lookup_bypassed
The customer's card was issued by a bank where 3D Secure verifications are bypassed and opportunity for liability shift is negated. If you prefer not to continue transactions with this status, ask the customer for a different payment method.
false false No B
lookup_enrolled
This is the initial status of 3DS call where the cardholder is enrolled. This status can be returned when your customer clicked on the Braintree provided cancel button in the 3D Secure authentication window to cancel the 3D Secure flow.
true false Yes Y
lookup_error
An error occurred during the lookup and caused 3D Secure authentication to fail.
false false No Null
lookup_not_enrolled
Your customer is not enrolled in 3D Secure.
false false No N
unsupported_card
Your account is not set up to authenticate the customer's provided card brand with 3D Secure. Only the following card brands are currently supported: Visa, MasterCard, American Express, and Maestro. Contact our Support team to confirm your 3D Secure configuration. 3D Secure for zero amount is not supported for any card brand in Brazil.
false false No Null
unsupported_account_type
Your merchant account is not set up to accept this card type. Only credit and debit can be accepted, but accepted values depend on your configuration. Contact our Support team to confirm your 3D Secure configuration.
false false No Null
unsupported_three_d_secure_version
Your merchant account is not set up to use the 3D Secure version requested.
false false No Null
challenge_required
The issuer requires a challenge to complete the 3D Secure authentication.
true false Yes Y
authenticate_rejected
The issuer has rejected the 3D Secure authentication. It is not recommended to proceed to a payment.
false false Yes Y
authenticate_frictionless_failed
The issuer is not allowing the customer to complete a 3D Secure challenge, but may be willing to accept a payment without liability shift.
false false Yes Y
lookup_failed_acs_error
An error occurred in the issuer's system during the 3D Secure lookup and caused the authentication to fail.
false false No U
authenticate_failed_acs_error
An error occurred in the issuer's system during the 3D Secure challenge and caused the authentication to fail.
false false Yes Y
data_only_successful
A status returned when using data-only to collect data but skip authentication.
false false No Y
lookup_card_error
A status returned when using there is an issue validating the card by the MPI provider.
false false Yes U
lookup_server_error
A status returned when there is an issue with directory server.
false false Yes U
exemption_low_value_successful
Successfully applied a low value exemption.
false false No Null
exemption_tra_successful
Successfully applied a transaction risk analysis exemption.
false false No Null
mpi_server_error
An error occurred on the 3D Secure MPI providers system.
false false No Null
skipped_due_to_rule
3D Secure was skipped as stated by the matched 3D Secure Rule.
false false No Null

Recurring Transactionsanchor

Recurring Billinganchor

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. Launch the 3D Secure authentication flow for your customer.
  • For JavaScript, use the client-side verifyCard() function. The resulting nonce in verifyPayload will contain a new, 3D Secure enriched nonce.
  • For Android / iOS, verify using 3D Secure in your client. Successful results will have a new payment method nonce that is enriched with 3D Secure data.
  1. 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. If you need to re-establish SCA then repeat the above steps but call Subscription.update() instead of Subscription.create()

Recurring Transactions with fixed amount and scheduleanchor

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 initiated transactions (MIT) without requiring 3D Secure authentication.

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

Subsequent Transactions without fixed amount or scheduleanchor

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 TransactionSource parameter of the Transaction.Sale() API call.

Exception for payment methods stored before September 2019anchor

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 successfully 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: Merchant Initiated Authentication (3RI)