important

We will be updating our root SSL provider for API traffic to align with security standards starting April, 2020 in sandbox and May, 2020 in production. To avoid interruption to your checkout workflows, please update your SDK version to the appropriate minimum versions specified on this page.

The Braintree Android SDK helps you accept payments in your Android app.

Requirements

  • Android API >= 16

It goes without saying, but we’ll say it anyway: we always recommend using the latest versions of our SDKs.

In order to communicate securely with the Braintree gateway starting April, 2020 in sandbox and May, 2020 in production, you must use at least version 2.8.0 of the Android SDK.

Installation

There are several ways to include Braintree in your project, but Gradle is the preferred build system for working with the Braintree Android SDK.

Build systems

Gradle

In your build.gradle, add the following:

Groovy 
dependencies {
  compile 'com.braintreepayments.api:braintree:2.22.0'
}

Then, continue to Browser switch setup below.

Maven

You must be using android-maven-plugin 4.1.0 or higher.

In your pom.xml add the following:

XML 
<dependencies>
  <dependency>
    <groupId>com.braintreepayments.api</groupId>
    <artifactId>braintree</artifactId>
    <version>[2.0.0,)</version>
    <type>aar</type>
    <configuration>
      <manifestMergeLibraries>true</manifestMergeLibraries>
    </configuration>
  </dependency>
</dependencies>

Then, continue to Browser switch setup below.

Browser switch setup

Some of our payment flows utilize a browser switch, such as PayPal, Venmo, and 3D Secure verification. A URL scheme must be defined to return to your app from the browser.

Edit your AndroidManifest.xml to include BraintreeBrowserSwitchActivity and set the android:scheme:

XML 
<activity android:name="com.braintreepayments.api.BraintreeBrowserSwitchActivity"
    android:launchMode="singleTask">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="${applicationId}.braintree" />
    </intent-filter>
</activity>
important

Your app's URL scheme must begin with your app's package ID and end with .braintree. For example, if the Package ID is com.your-company.your-app, then your URL scheme should be com.your-company.your-app.braintree. ${applicationId} is automatically applied with your app's package when using Gradle.

Note: The scheme you define must use all lowercase letters. If your package contains underscores, the underscores should be removed when specifying the scheme in your Android Manifest.

Initialization

The setup of BraintreeFragment is simply a call to BraintreeFragment.newInstance(activity, authorization) with the current Activity and either a client token, or tokenization key.

Java 
@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);

  try {
    mBraintreeFragment = BraintreeFragment.newInstance(this, mAuthorization);
    // mBraintreeFragment is ready to use!
  } catch (InvalidArgumentException e) {
    // There was an issue with your authorization string.
  }
}

This static method will:

  • Prepare a BraintreeFragment.
  • Add the BraintreeFragment to the given activity.
  • Check for validity on the given mAuthorization string.

Register listeners

Braintree provides several interfaces which will be called when events occur. Any Braintree interface that BraintreeFragment's host Activity implements will be automatically managed for you. However, if you wish to manage the Braintree listeners yourself, use BraintreeFragment#addListener. In this case, be sure to use BraintreeFragment#removeListener to clean up in the event of a state change to avoid memory leaks.

The following interfaces may be implemented to receive events:

  • PaymentMethodNonceCreatedListener is called when a PaymentMethodNonce has been successfully tokenized. Send the nonce from this PaymentMethodNonce to your server to create a transaction.

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

  • ConfigurationListener is called after configuration has been retrieved from Braintree. The Configuration class contains information about your current environment as well as information about which payment methods are currently available.

  • BraintreeCancelListener is called when BraintreeFragment is notified of a Activity#RESULT_CANCELED result code in Fragment#onActivityResult.

    Java 
    @Override
public void onCancel(int requestCode) {
  // Use this to handle a canceled activity, if the given requestCode is important.
  // You may want to use this callback to hide loading indicators, and prepare your UI for input
}

  • BraintreeErrorListener is called when there has been an error. ErrorWithResponse is called when there are validations errors with the request. Exception is thrown when an error such as a network issue or server error occurs.

    Java 
    @Override
public void onError(Exception error) {
  if (error instanceof ErrorWithResponse) {
    ErrorWithResponse errorWithResponse = (ErrorWithResponse) error;
    BraintreeError cardErrors = errorWithResponse.errorFor("creditCard");
    if (cardErrors != null) {
      // There is an issue with the credit card.
      BraintreeError expirationMonthError = cardErrors.errorFor("expirationMonth");
      if (expirationMonthError != null) {
        // There is an issue with the expiration month.
        setErrorMessage(expirationMonthError.getMessage());
      }
    }
  }
}

ProGuard

A ProGuard configuration is provided as part of the Braintree Android SDK. There is no need to add any Braintree specific rules to your ProGuard configuration.

See also