Client-Side Implementation

Android v4SDK

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

important

The SSL certificates for all Braintree SDKs are set to expire by June 31, 2025. This will impact existing versions of the SDK in published versions of your app. To reduce the impact, upgrade the Android SDK to version 4.45.0+ or version 5.0.0+ for the new SSL certifications.

If you do not decommission your app versions that include the older SDK versions or force upgrade your app with the updated certificates by the expiration date, 100% of your customer traffic will fail.

Setup

In order to add Local Payment Methods to your Android application, you must declare a URL scheme in your AndroidManifest.

Get the SDK

Add the following in your app-level build.gradle:

dependencies {
  implementation 'com.braintreepayments.api:local-payment:4.39.0'
}

Determine which merchant account to use

This will determine which PayPal credentials are used for the transaction, and must match the merchant account specified with any other calls in the transaction lifecycle (e.g. Transaction.sale). Many merchants use a separate merchant account for local payments. Other merchants use separate merchant accounts for transactions in different currencies. It is not possible to switch merchant accounts between the start and finish of a local payment transaction, so it is important to determine the correct one from the start.

Invoke payment flow

You can implement a custom UI, such as your own iDEAL button.

The following is a list of valid paymentType, countryCodeAlpha2, and currencyCode values for each Local Payment Method:

The paymentTypeCountryCode parameter is only required for payment methods with multiple potential country codes. If a paymentTypeCountryCode is not provided, then the countryCode value will be used as the paymentTypeCountryCode.

The following is a list of required parameters for each Local Payment Method, as well as any applicable transaction limits:

The following is a list of business identification numbers (bic) you can optionally include to identify the specific bank when processing iDEAL as a payment payment method:

note

Note: bic can only be included for iDEAL payment methods. If you are processing a payment method other than iDEAL you do not need to include a bic.

Next, create a BraintreeClient with a ClientTokenProvider or Tokenization Key. Instantiate a LocalPaymentClient to start the payment flow and implement a LocalPaymentListener to receive results.

class MyActivity extends FragmentActivity implements LocalPaymentListener {

  private BraintreeClient braintreeClient;
  private LocalPaymentClient localPaymentClient;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    braintreeClient = new BraintreeClient(this, new ExampleClientTokenProvider());
    localPaymentClient = new LocalPaymentClient(this, braintreeClient);
    localPaymentClient.setListener(this);
  }

  private void startLocalPayment() {
    PostalAddress address = new PostalAddress();
    address.setStreetAddress("836486 of 22321 Park Lake");
    address.setCountryCodeAlpha2("NL");
    address.setLocality("Den Haag");
    address.setPostalCode("2585 GJ");

    LocalPaymentRequest request = new LocalPaymentRequest();
    request.setPaymentType("ideal");
    request.setAmount("1.01");
    request.setAddress(address);
    request.setPhone("639847934");
    request.setEmail("joe@getbraintree.com");
    request.setGivenName("Jon");
    request.setSurname("Doe");
    request.setShippingAddressRequired(true);
    request.setCurrencyCode("EUR");

    localPaymentClient.startPayment(request, (result, error) -> {
      // do any preprocessing result.getPaymentId()
      localPaymentClient.approvePayment(MyActivity.this, result);
    });
  }

  @Override
  public void onLocalPaymentSuccess(@NonNull LocalPaymentNonce localPaymentNonce) {
      // send localPaymentNonce.getString() to server
  }

  @Override
  public void onLocalPaymentFailure(@NonNull Exception error) {
    if (error instanceof UserCanceledException) {
      // user canceled
    } else {        
      // handle error
    }
  }
}

If you are using using an Activity and your Activity's launch mode is singleTop, singleTask, or singleInstance you will also need to override onNewIntent:

class MyActivity extends FragmentActivity {

  @Override
  protected void onNewIntent(Intent newIntent) {
    super.onNewIntent(newIntent);

    setIntent(newIntent);
  }
}

important

You must implement Braintree webhooks in order to accept Local Payment Methods. See Server-side for details.

Shipping addresses

If you need a shipping address to ship physical goods, set shippingAddressRequired to true on your LocalPaymentRequest. This setting will prompt your customer to provide shipping details. If you have already collected these details from your customer, you can pass the shipping details within LocalPaymentRequest to avoid having your customer provide them again.

If you are not shipping physical goods, then use the default value of false for shippingAddressRequired. This setting will prompt your customer to provide just the basic information like givenName, surname, phone, and email. If you have already collected these details from your customer, you can pass them on LocalPaymentRequest to avoid having your customer provide them again.