Payment flow

  • If the authentication is completed successfully or none was required, use the returned nonce to create a transaction.

Create a transaction

To create a 3D Secure transaction:

  1. Pass the payment method nonce you received from your client to your server.
  2. Tell the Braintree gateway how to handle 3D Secure failures.

The gateway uses a boolean to indicate whether or not 3D Secure verification must succeed before creating a transaction. The options.three_d_secure.required parameter defaults to true, unless you explicitly pass false to indicate that you are willing to accept the risk of transactions without a successful authentication.

Ruby
Click to copy
Copied
result = Braintree::Transaction.sale(
  :amount => "100.00",
  :payment_method_nonce => nonce_from_the_client,
  :options => {
    :three_d_secure => {
      :required => true
    }
  }
)
important

3D Secure information is lost when a 3D Secured payment_method_nonce is used outside of a Braintree::Transaction.sale() call.

Vaulted credit card nonces

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.

Ruby
Click to copy
Copied
result = Braintree::PaymentMethodNonce.create("PAYMENT_METHOD_TOKEN")
nonce = result.payment_method_nonce.nonce

Server-side details

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.

Ruby
Click to copy
Copied
result = Braintree::PaymentMethodNonce.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.

Ruby
Click to copy
Copied
transaction = Braintree::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 codes

Here are the possible 3D Secure statuses and their liability shifts.

Status Liability Shifted Liability Shift Possible
"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.
false false
"lookup_error"
An error occurred during the lookup and caused 3D Secure authentication to fail.
false false
"lookup_not_enrolled"
Your customer’s card-issuing bank is domiciled within the United States and is not certified by the associated card brand to allow 3D Secure transactions.
false false
"lookup_bypassed"
Your customer's transaction returned a B value for the three_d_secure_info.enrolled parameter and the transaction was not authenticated with 3D Secure.
false false
"authenticate_successful_issuer_not_participating"
Your customer’s card-issuing bank is domiciled outside of the US and is not certified by the associated card brand to allow 3D Secure transactions.
true true
"authentication_unavailable"
Your Braintree gateway is not 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. The setup process for Mastercard can take 2-3 business days and American Express can take up to 7 business days.
false false
"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.
false true
"authenticate_successful"
The transaction was successfully authenticated with 3D Secure.
true true
"authenticate_attempt_successful"
The provided card brand authenticated this 3D Secure transaction without password confirmation from the customer.
true true
"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.
false true
"authenticate_unable_to_authenticate"
An error occurred with the card-issuing bank that caused the 3D Secure authentication to fail. Have the customer attempt the transaction again.
false true
"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.
false true

Server-side errors

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 the nonce was generated using verify3DS, then the transaction will not be rejected.

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

Advanced server-side options

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.

The required flag tells the Braintree gateway that you expect 3D Secure authentication to have succeeded on this transaction. This helps protect you against malicious users tampering with your front-end code and bypassing 3D Secure completely. Setting it to true is the safest option when you expect a transaction to include a 3D Secure authentication. This will only allow transactions to go through if authentication has been attempted and succeeded, or has been attempted and not been possible (in the case of cards not participating in 3D Secure).

The required flag may be changed on a per-transaction basis. We strongly recommend that you default to setting this to true; however, 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.

Next: Testing and Go Live →

Still have questions?

If you can’t find an answer, contact our Support team.