3D Secure

Advanced Optionsanchor

Table of Contentsanchor

Liability shiftanchor

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.

  1. Callback
  2. Promise
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
});
  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).
important

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

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.

  1. Ruby
  2. Python
  3. PHP
  4. Node
  5. Java
  6. C#
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
  2. Python
  3. PHP
  4. Node
  5. Java
  6. C#
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 Dataanchor

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:

  • browser color depth
  • browser Java enabled
  • browser JavaScript enabled
  • browser language
  • browser screen height and width
  • browser time zone
  • device channel

Verifying a vaulted cardanchor

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.

  1. Ruby
  2. Python
  3. PHP
  4. Node
  5. Java
  6. C#
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 challengeanchor

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 Brazilanchor

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.

  1. Callback
  2. Promise
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 3DSanchor

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

  • A non-network tokenized card is a standard credit card. Access to the card's primary account number (PAN) makes 3DS verification possible.
  • A network tokenized card is a generated virtual card with a device-specific account number (DPAN) that is used in place of the underlying source card. These cards cannot be used with 3DS.

Drop-in UI with Google Payanchor

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

Custom UI with Google Payanchor

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 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.

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

SCA Exemptionsanchor

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 Typesanchor

Low Value Exemptionanchor

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 Exemptionanchor

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 Exemptionsanchor

Requesting an exemption during Transaction.saleanchor

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 Secureanchor

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 Onlyanchor

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. Presently, Data-Only 3D Secure is only supported on MasterCard (the MasterCard protocol name is "Identity Check Insights"), and in select regions/processors. 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 does not support data-only, a standard 3D Secure lookup will occur. However, if the processor does not support data-only, you will receive a 915126 validation error.

Visa Digital Authentication Frameworkanchor

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.


Next Page: Authentication Insight →