3D Secure

Server-Side Implementationanchor

Create a transactionanchor

To create a 3D Secure transaction, you will first need to verify the card with 3D Secure on the client side. The result of the client-side call will be a payload with 3D Secure authentication details, which can be referenced by using the returned 3D Secure upgraded nonce or the authentication ID. Either of these can be used to reference the authentication when creating the transaction.

Create a transaction using a 3D Secure upgraded nonceanchor

To create a 3D Secure transaction, make a server-side sale call using the payment method nonce 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. Ruby
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 a Payment Method: Create call without a verify_card flag.

Create a transaction with an 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. A payment method token can be used instead of a payment method nonce if you provide the 3D Secure authentication via an authentication ID.

  1. Ruby
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
  }
)

Use 3D Secure when verifying a cardanchor

To use 3D Secure during a card verification, you will first need to verify the card with 3D Secure on the client side. The result of the client-side call will be a payload with 3D Secure authentication details, which can be referenced by using the returned 3D Secure upgraded nonce or the authentication ID.

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 nonce, 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. A payment method token can be used instead of a payment method nonce if you provide a three_d_secure_authentication_id.

Create a new payment methodanchor

Make a server-side call using the payment method nonce 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 nonce, 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. A payment method token can be used instead of a payment method nonce if you provide a three_d_secure_authentication_id.

Vaulted credit card noncesanchor

When creating a 3D Secure transaction with a vaulted card, the process is essentially the same as above – just use the payment method token associated with the vaulted card to create the payment method nonce.

  1. Ruby
result = gateway.payment_method_nonce.create("PAYMENT_METHOD_TOKEN")
nonce = result.payment_method_nonce.nonce

Server-side detailsanchor

Payment method nonces will include 3D Secure information such as liability_shifted and liability_shift_possible. This can be used for server-side risk checking before creating transactions.

  1. Ruby
result = gateway.payment_method_nonce.find("nonce_string")
info = result.payment_method_nonce.three_d_secure_info
if info.nil?
  return # This means that the nonce was not 3D Secured
end
info.liability_shifted?
info.liability_shift_possible?
info.enrolled
info.status

Transactions also expose 3D Secure info. This can be used for reporting on the details of a 3D Secured transaction after creating it.

  1. Ruby
transaction = gateway.transaction.find("the_transaction_token")
info = transaction.three_d_secure_info
if info.nil?
  return # This means that the nonce was not 3D Secured
end
info.liability_shifted?
info.liability_shift_possible?
info.enrolled
info.status

Status codesanchor

Below are the possible 3D secure statuses, along with their liability shifts and 3D Secure enrolled values. This table also shows whether a transaction will be rejected by the 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 false Yes 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_signature_verification_failed"
An error occurred during the lookup and the returned authentication message is no longer secure. 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 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
"authentication_bypassed"
The customer's card was issued by a bank where 3D Secure authentication steps are bypassed. If you prefer not to continue transactions with this status, ask the customer for a different payment method.
false true No Y
"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 Yes Y
"lookup_card_error"
A status returned when using there is an issue validating card by 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 occured 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
important

For American Express SafeKey, liabilityShifted may be returned as true but Amex may later revoke the liability shift for the transaction based on your merchant behavior and fraud rate.

Server-side errorsanchor

A transaction result may contain a validation error when processing a 3D Secure transaction.

Additionally, if you specify that 3D Secure is required but the customer did not pass 3D Secure authentication or 3D Secure authentication was not attempted, the transaction will be rejected by the Braintree gateway. If the customer's card is not enrolled in a 3D Secure program but you used a nonce generated from a 3D Secure client-side verification, then the transaction will not be gateway rejected.

If you call Transaction.sale() without performing a 3D Secure authentication, the issuing bank may return a soft decline indicating that the issuing bank will not proceed with the transaction without requiring the cardholder to authenticate. In this case, _2099 - Cardholder Authentication Required, or another soft decline code, will be returned. You can simulate this scenario by creating a test transaction in Sandbox with an amount of 2099.

  1. Ruby
if result.transaction.gateway_rejection_reason == Braintree::Transaction::GatewayRejectionReason::ThreeDSecure
  # Ask for a new payment method
end

Advanced server-side optionsanchor

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, which indicates whether or not you expect 3D Secure authentication to have succeeded on a transaction. When you create a transaction with a 3D Secure enriched nonce, the options().threeDSecure().required() parameter defaults to true, which means that transactions will be rejected unless they have successful 3D Secure. If 3D Secure is not present, it 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 you 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.

Authentication Insightanchor

Authentication Insight provides you with more details about the regulatory environment and applicable customer authentication regulation for a potential transaction. You can request Authentication Insight for a customer's payment method stored in the Vault.

To retrieve the Authentication Insight for a nonce, set authentication_insight to true and specify your merchant_account_id.

  1. Ruby
create_request = {
  merchant_account_id: "merchant-account-id",
  authentication_insight: true
}

result = gateway.payment_method_nonce.create(
  "payment-method-token",
  payment_method_nonce: create_request
)

regulation_environment = result.payment_method_nonce.authentication_insight[:regulation_environment]

Next Page: Recurring Transactions →