Advanced Options

JavaScript v3

• Current Braintree SDKs
• Android v5
• iOS v6
• JavaScript v3
• Previous Versions
• Android v4
• iOS v5
• JavaScript v2

Table of Contents

Liability shift

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.

These parameters pass through the client-side first and should not be trusted for your server-side risk assessment. They should be used for UI flow only.

threeDSecure.verifyCard({
  amount: '500.00',
  nonce: NONCE_FROM_INTEGRATION,
  bin: BIN_FROM_INTEGRATION,
  onLookupComplete: function (data, next) {
    // use 'data' here, then call 'next()'
    next();
  }
}, function (err, response) {
  var liabilityShifted = response.liabilityShifted; // true || false
  var liabilityShiftPossible =  response.liabilityShiftPossible; // true || false
});

On the server side, Payment method single-use-tokens expose 3D Secure info. This can be used for reporting on the details of a 3D Secured transaction after creating it.

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

Collecting Device Data

Submitting additional device data to 3D Secure may reduce rejections and/or the need for authentication challenges for customers. Set the collectDeviceData as true in the 3DS lookup parameters to enable collection of additional device data.

The following device attributes are sent to 3D Secure when this option is enabled:

Verifying a vaulted card

To verify a vaulted credit card, first generate and return a payment method nonce for the vaulted credit card on the server.

The process of generating a nonce for a vaulted card is the same as for a credit card. On the server, just use the payment method token associated with the vaulted card.

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

Then on the client, you can use the verifyCard() method just as before and pass it the newly-generated nonce.

Requesting a cardholder challenge

To override the default behavior of 3DS and request the cardholder's bank to issue an authentication challenge, pass challengeRequested: true on the verifyCard() call.

Selecting an account type for combo cards in Brazil

When processing Brazilian cards domestically, customers with combo cards should be given the opportunity to select the account type of their card. To do this, generate a UI for this selection and reflect that choice in the accountType field of the 3D Secure verifyCard() call, as well as the corresponding transaction, payment method or customer API call.

threeDSecure.verifyCard({
  amount: '500.00',
  nonce: NONCE_FROM_INTEGRATION,
  bin: BIN_FROM_INTEGRATION,
  accountType: 'credit',
  onLookupComplete: function (data, next) {
    // use 'data' here, then call 'next()'
    next();
  }
}, function (err, response) {
  var liabilityShifted = response.liabilityShifted; // true || false
  var liabilityShiftPossible =  response.liabilityShiftPossible; // true || false
});

Verify Google Pay card using 3DS

We support 3DS for Google Pay non-network tokenized cards. Google Pay cards can be tokenized in one of two ways:

Drop-in UI with Google Pay

If 3DS was requested, Google Pay cards that are non-network tokenized will automatically be processed for 3DS verification.

Custom UI with Google Pay

To process non-network tokenized Google Pay cards for 3DS verification, include a Google Pay nonce as the `nonce` field on your `threeDSecureParameters`. See the [Google Pay configuration guide](/braintree/docs/guides/google-pay/configuration) for how to generate a Google Pay nonce. Once you have generated a nonce, you should check if your Google Pay nonce is non-network tokenized.

if (nonce.isNetworkTokenized === false) {
   // eligible for 3DS Verification, call verifyCard()
 }

SCA Exemptions

Merchants can request an exemption from SCA requirements on certain transactions. Exemptions are granted completely at the discretion of the issuer, and are never guaranteed. If an exemption is requested and subsequently granted by the issuer, then SCA will not be required, however the liability remains with the merchant and is not shifted to the issuer. There are a few different exemption types and each has its own set of conditions to determine whether they are applicable.

SCA Exemption Types

Low Value Exemption

Low value exemptions can be requested on transactions that total less than 30 EUR. Caveats are that no more than five transactions on a payment instrument in a row can forego SCA based on this exemption and SCA is required if the customer’s total payments exceed 100 EUR since the last time SCA was applied.

Transaction Risk Analysis Exemption

Transaction Risk Analysis (TRA) exemptions allow an acquirer to request approval from issuing banks to avoid applying SCA as part of the transaction call up to certain limits based on the acquirers overall fraud rate calculated on a rolling quarterly basis (90 days). For this exemption to be considered the transaction must total less than 250 EUR. TRA exemptions are not enabled by default, to request access to this exemption please contact support@braintreepayments.com.

How to request SCA Exemptions

Requesting an exemption during Transaction.sale

If you do not perform a 3D Secure authentication, but wish to request a SCA exemption on your transaction, you can do so by supplying the scaExemption field via the Transaction.sale() call. If possible, the exemption request will be sent with the transaction. However, note that if you perform a 3D Secure authentication, nothing about exemptions during Transaction.sale() overrides normal 3DS logic (for example, all the normal logic concerning whether transactions are rejected when 3DS is required is applied before exemptions are even considered).

If you perform a 3D Secure authentication with your own MPI provider and receive an SCA exemption from the issuer via 3D Secure, then you should also use this method.

Requesting an exemption during 3D Secure

To request a specific SCA exemption when performing a 3D Secure authentication, use the requestedExemptionType option in the verifyCard() call. The requested exemption will be applied only if the exemptions conditions are met. If the exemption applies, we will request that no challenges be issued during 3D Secure authentication. In this case no exemption information is required in the Transaction.sale() call.

If the exemptions conditions have not been met, then a standard 3D Secure authentication will be attempted.

Data Only

A data-only 3D Secure call is entirely frictionless, but no liability shift is granted. This variant of 3D Secure is used as a way to seek an improvement in authorization rates from issuing banks, without increasing the risk to issuers via fraud liability shift. The MasterCard protocol name is "Identity Check Insights".

Presently, Data-Only 3D Secure is supported on MasterCard (including Maestro) and Visa, on select processors, and is not supported in PSD2 regulated countries. To find out if your merchant account supports data-only, please look at the Merchant Account section in the control panel and then confirm that the 3D Secure Data-Only Card Types section is present and the relevant card brand logo is displayed.

To use data-only 3D Secure calls, add the dataOnlyRequested boolean to your verifyCard() call. If the card brand and processor support data-only, then you should receive a response with the dataOnlySuccessful status in the onLookupComplete() callback. If the card brand or processor does not support data-only, a standard 3D Secure lookup will occur.

An alternative method to request data-only is using the 3D Secure Rules Manager.

Visa Digital Authentication Framework

Visa Digital Authentication Framework (DAF) is a feature that allows an authentication payment credential to be established using an issuer step up. With this payment credential all subsequent transactions for the same payment instrument on the same merchant should be frictionless (with a full liability shift). A payment credential is valid for up to 2 years.

If the transaction is subject to PSD2, then Visa DAF has to be used together with an acquirer TRA exemption. For the other regions which support Visa DAF no exemption is required. The regions that currently support Visa DAF are North America (cross border only, not domestic), Latin America/Caribbean, Europe, Asia Pacific (except Japan/India/Bangladesh), Central Europe/Middle East/Africa (except Russia).

Visa DAF is requested by adding requestVisaDAF to your verifyCard() call. To confirm your eligibility to use Visa DAF please contact your acquiring bank.