Server-Side Implementation

RubySDK

• Current Braintree SDKs
• Java
• .NET
• Node.js
• PHP
• Python
• Ruby

note

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

This guide shows our legacy integration for 3D Secure. To use 3DS2 instead:

• If you've already integrated 3DS1, see our 3DS2 migration guide.
• If you don't use 3DS yet, see our full 3D Secure integration guide that we've updated for 3DS2.

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, make a server-side sale call using the payment method nonce you received from your client when you verified the credit card.

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

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 outside of a 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.

result = gateway.payment_method_nonce.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.

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.

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 codes

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.

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 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 you used a nonce generated from a 3D Secure client-side verification, then the transaction will not be gateway rejected.

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 gateway uses a boolean to indicate 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.three_d_secure.required parameter defaults to true. This only allows 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).

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 true on transactions that do not go through 3D Secure, those transactions will be gateway rejected.