note

We are currently working on upgrading this 3D Secure integration in preparation for 3DS 2.0 and PSD2 Strong Consumer Authentication (SCA) compliance requirements in 2019.

See our 3DS 2.0 Adoption guide for details.

Payment flow

Generate a client token

important

You must generate a client token if you want to use 3D Secure. Tokenization keys can't be used when processing 3D Secure transactions.

Before you can call ThreeDSecure#performVerification, you will need to setup the SDK and initialize BraintreeFragment with a client token generated on your server.

If you are not using Gradle to integrate Braintree, make sure to add the 3D Secure Activity to your AndroidManifest.xml:

XML
Copy
Copied
<activity android:name="com.braintreepayments.api.threedsecure.ThreeDSecureWebViewActivity" />

Specify a merchant account

If you would like to use a merchant account ID other than your default, specify the merchant_account_id when generating the client token.

note

This merchant account ID must match the merchant account ID used to create the transaction.

Render a checkout page

You can structure your native checkout flow however you'd like. If you don't already have a credit card form, consider our Drop-in UI.

When using Drop-in, users will be prompted to authenticate with 3D Secure if an amount is specified with DropInRequest#amount and DropInRequest#requestThreeDSecureVerification is set to true.

For a custom integration when the user taps on the final checkout button, but before creating a transaction on your server, you should call ThreeDSecure#performVerification.

Your BraintreeErrorListener setup with BraintreeFragment should be prepared to handle any errors with the 3D Secure verification.

Verify a credit card

Once you initialize an instance of BraintreeFragment, you can verify transactions with ThreeDSecure#performVerification. This call will refer to the card data based on the payment method nonce and challenge the cardholder with a 3D Secure authentication, if the card is enrolled in a 3D Secure program (e.g. Verified by Visa).

The transaction amount is required at verification for two reasons. First of all, it's an additional check to make sure the transaction being verified is the same as the one that is eventually authorized and settled. For this reason, the amount submitted for verification must match the amount sent to the Braintree server for authorization. Additionally, some issuers use the amount to help determine whether they should challenge the user to authenticate.

note

To use 3D Secure, integrate with Android SDK v2.10.0+.

Java
Copy
Copied
ThreeDSecureRequest threeDSecureRequest = new ThreeDSecureRequest()
    .nonce(nonce)
    .amount("5.00");
ThreeDSecure.performVerification(mBraintreeFragment, threeDSecureRequest);

If a user-facing authentication flow is required, an Activity will be presented to the user.

Once the user completes the 3D Secure process, BraintreeFragment will notify the BraintreeListeners with the result. Be prepared to handle the errors in your BraintreeErrorListener or the PaymentMethodNonce in PaymentMethodCreatedListener. When your PaymentMethodCreatedListener receives a PaymentMethodNonce, transmit PaymentMethodNonce#getNonce() to your server and create a transaction.

Java
Copy
Copied
@Override
public void onError(Exception error) {
  // Handle the error
}

@Override
public void onPaymentMethodNonceCreated(PaymentMethodNonce paymentMethodNonce) {
  String paymentMethodNonce = paymentMethodNonce.getNonce();
  // Upload paymentMethodNonce to your server.
}

Verify a vaulted credit card

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

Then on the client, you can use the ThreeDSecure#performVerification method just as before and pass it the newly-generated nonce.

Java
Copy
Copied
ThreeDSecureRequest threeDSecureRequest = new ThreeDSecureRequest()
        .nonce(NONCE_FROM_YOUR_SERVER)
        .amount(amount);

ThreeDSecure.performVerification(mBraintreeFragment, threeDSecureRequest);

Verify a card from raw details or a payment method

To perform a verification on raw card details, we provide a convenience method:

Java
Copy
Copied
CardBuilder cardBuilder = new CardBuilder()
  .cardNumber("4111111111111111")
  .expirationDate("12/2020");

ThreeDSecure.performVerification(mBraintreeFragment, cardBuilder, amount);

Validation errors

Braintree will evaluate any fields passed against Cardinals' documentation. You will receive a validation error from Braintree if a field is incorrect.

American Express SafeKey

If you're a US-based merchant configured for Amex SafeKey, you need to pass additional parameters for the transaction to be evaluated for fraud.

We recommend passing most, if not all, of the parameters to qualify for Amex SafeKey. The more parameters you send, the more likely you are to successfully contest a chargeback.

Java
Copy
Copied
ThreeDSecureRequest request = new ThreeDSecureRequest()
  .nonce("a-nonce")
  .amount("1.00")
  .shippingMethod("01")
  .mobilePhoneNumber("8101234567")
  .email("test@example.com")
  .billingAddress(new ThreeDSecurePostalAddress()
    .firstName("Joe")
    .lastName("Guy")
    .streetAddress("555 Smith Street")
    .extendedAddress("#5")
    .locality("Oakland")
    .region("CA")
    .postalCode("12345")
    .countryCodeAlpha2("US")
    .phoneNumber("12345678"));

Although these additional parameters are only necessary when using Amex SafeKey, you can safely pass them for other card brands as well.

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

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.

Java
Copy
Copied
@Override
public void onPaymentMethodNonceCreated(PaymentMethodNonce paymentMethodNonce) {
  CardNonce cardNonce = (CardNonce) paymentMethodNonce;

  boolean liabilityShifted = cardNonce.getThreeDSecureInfo().isLiabilityShifted(); // true || false
  boolean liabilityShiftPossible = cardNonce.getThreeDSecureInfo().isLiabilityShiftPossible(); // 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 Amex may later revoke the liability shift for the transaction based on your merchant behavior and fraud rate.

Next Page: Server-side →

Still have questions?

If you can’t find an answer, contact us