availability

Visa Checkout is currently in a limited release to eligible merchants, and the API is subject to change. It is only available for Android v2, iOS v4, and JavaScript v3.

Contact us at visacheckout-requests@braintreepayments.com to request access to the release.

Vaulting Visa Checkout

Your customer's Visa Checkout card selection can be saved to your Vault and reused for future transactions, just like a credit card:

Ruby
Copy
Copied
result = gateway.payment_method.create(
  :customer_id => "131866",
  :payment_method_nonce => nonce_from_the_client
)
This code snippet now uses gateway instance methods instead of class-level methods. Learn more.

You can also save the customer's Visa Checkout card to your Vault at the same time as your transaction by using Transaction.sale() with options.store_in_vault or options.store_in_vault_on_success.

important

3D Secure information is lost when a 3D Secured payment_method_nonce is vaulted. Vaulted payment methods can be used to perform subsequent transactions; however, information about shifted liability or any 3D Secure specific details will not apply. If you want to create a 3D Secured transaction from a vaulted Visa Checkout card, you must create a payment method nonce using the vaulted card's payment method token.

Creating a one-time transaction

Creating a one-time transaction with a Visa Checkout card is the same as creating any other transaction with a nonce. The primary difference is that the results of the 3D Secure authorization should first be examined prior to creating the transaction using the nonce.

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
Copy
Copied
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

if info.liability_shifted?
  # Proceed with transaction.
  result = gateway.transaction.sale(
    :amount => "10.00",
    :payment_method_nonce => nonce_from_the_client,
    :options => {
      :submit_for_settlement => true
    }
  )

  if result.success?
    # See result.transaction for details
  else
    # Handle errors
  end
elsif info.liability_shift_possible?
  # Examine contents of "info.status" and advise user according to the table below.
end
This code snippet now uses gateway instance methods instead of class-level methods. Learn more.

Liability shift

  1. liabilityShifted indicates that 3D Secure worked and authentication succeeded. This will also be true if the issuing bank does not support 3D Secure, but the payment method does. In both cases, the liability for fraud has been shifted to the bank. You should go on creating a transaction using the new nonce.
  2. liabilityShiftPossible indicates that the payment method was eligible for 3D Secure. If liabilityShifted is false, then the user failed 3D Secure authentication. In this situation, the card brands recommend asking the user for another form of payment. However, if you have server-side risk assessment processes that allow for it, you can still use the new nonce to create a transaction. If you want to use a nonce that did not pass 3D Secure authentication, you need to set the required option to false in your server integration.
  3. If both of the above values are false then this card was ineligible for 3D Secure. You can continue to create the transaction with the new nonce. However, liability shift will not apply to this transaction. This case may be useful if you would like to ask the user for additional verification (AVS, etc).

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_enrolled"
Your customer clicked on the Braintree-provided cancel button in the 3D Secure authentication window. This can only occur if your setup allows customers to cancel the 3D Secure flow.
true 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

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

Ruby
Copy
Copied
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
This code snippet now uses gateway instance methods instead of class-level methods. Learn more.

Server-side errors

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

Additionally, if 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, the transaction will not be rejected.

Ruby
Copy
Copied
if result.transaction.gateway_rejection_reason == Braintree::Transaction::GatewayRejectionReason::ThreeDSecure
  # Ask for a new payment method
end
This code snippet now uses gateway instance methods instead of class-level methods. Learn more.

Next: Testing and Go Live →

Still have questions?

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