Client SDK

Setupanchor

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

Requirementsanchor

  • Android API >= 21

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

note

Our Android SDK and its modules follow semantic versioning. When updating your integration, be sure to update each module to the latest version.

Installationanchor

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

Get the SDKanchor

In your build.gradle, add the following:

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

Then, continue to Browser switch setup below.

Browser switch setupanchor

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:

  1. Xml
<activity android:name="com.braintreepayments.api.BraintreeBrowserSwitchActivity"
    android:launchMode="singleTask"
    android:exported="true">
    <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>
note

The android:exported attribute is required if your app compile SDK version is API 31 (Android 12) or later.

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.

Initializationanchor

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

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

Braintree provides several interfaces which will be called when events occur. Any Braintree interface that BraintreeFragment's host AppCompatActivity 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.
  1. 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.

  1. 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.
  1. 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());
            }
        }
    }
}

ProGuardanchor

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