Android

with Android Pay™

Follow the simple steps below and get started developing.

Overview

The Android SDK by Simplify allows you to create a card token (one time use token representing card details) in your Android app to send to a server to enable it to make a payment. By creating a card token, Simplify allows you to avoid sending card details to your server. The SDK can help with formatting and validating card information before the information is tokenized.

These steps will allow you to collect card information, retrieve a card token from Simplify, and send the card token to your server in order to charge a card.

View the sample app on GitHub
https://github.com/simplifycom/simplify-android-sdk-sample

Import the dependency link to maven

To import the Android SDK, include it as a dependency in your build.gradle file.

 compile 'com.simplify:simplify-android:3.0.0'

Note: Please make sure the 'minSdkVersion' value in your build.gradle file is 16 or later.

Initialize the SDK

Before you can communicate with Simplify to tokenize a card, you must first initialize the SDK with your public API key. To retrieve a usable public API key, first log in to simplify.com and click on "API Keys" in the dropdown menu next to your name. From there, you can create a new public key specific to your app, or use an existing one. Be sure to use a "live" key for your production app. Card tokens created with a sandbox API key can not be used to process real payments!

To initialize the SDK, set the API key in an instance of the Simplify object.

Simplify simplify;

@Override
public void onCreate() {
    super.onCreate();

    simplify = new Simplify();
    simplify.setApiKey("YOUR_API_PUBLIC_KEY");
}

Collect Card Information

When originating a payment from your mobile app, you must first collect and tokenize card information. There are a few ways to collect card information using the Simplify SDK:

  • Manually build a Card object (using your own custom card entry fields)
  • Retrieve a Card object from the provided CardEditor view
  • Android Pay

Manual Card / Custom UI

If you are using your own UI to collect card data from the user, you should build a Simplify Card object with this data. Refer to the CardToken API docs for the minimum required fields to tokenize a card.

// create a new card object
Card card = new Card()
    .setNumber("5555555555554444")
    .setExpMonth("01")
    .setExpYear("99")
    .setCvc("123")
    .setAddressZip("12345");

// tokenize the card
simplify.createCardToken(card, new CardToken.Callback() {
    @Override
    public void onSuccess(CardToken cardToken) {
        // ...
    }

    @Override
    public void onError(Throwable throwable) {
        // ...
    }
});

Using the CardEditor View

If you would prefer to use our provided UI to collect card information, simply drop the CardEditor view into your layout.

<com.simplify.android.sdk.CardEditor
    android:id="@+id/card_editor"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"/>

Within your context, you can register a state change listener to receive notifications when the valid state of the view has changed after the user has entered details. You may use this to enable/disable a checkout button as demonstrated below.

// init card editor
final CardEditor cardEditor = (CardEditor) findViewById(R.id.card_editor);
final Button checkoutButton = (Button) findViewById(R.id.checkout_button);

// add state change listener
cardEditor.addOnStateChangeListener(new CardEditor.OnStateChangedListener() {
    @Override
    public void onStateChange(CardEditor cardEditor) {
        // isValid() == true : card editor contains valid and complete card information
        checkoutButton.setEnabled(cardEditor.isValid());
    }
});

// add checkout button click listener
checkoutButton.setOnClickListener(new OnClickListener() {
    @Override
    public void onClick(View v) {
        // create a card token
        simplify.createCardToken(cardEditor.getCard(), new CardToken.Callback() {
            @Override
            public void onSuccess(CardToken cardToken) {
                // ...
            }

            @Override
            public void onError(Throwable throwable) {
                // ...
            }
        });
    }
});

By default, the CardEditor view will inherit the styles of the theme you apply to it's context. However, you may change the appearance in a couple of ways, as shown below.

Apply a new theme for EditText and/or AlertDialog (used to choose expiration date):

<style name="AppTheme" parent="Theme.AppCompat.Light.NoActionBar">
    <item name="colorAccent">@color/accent</item>
    <item name="android:editTextStyle">@style/EditText</item>
    <item name="buttonStyle">@style/Button</item>
    <item name="alertDialogTheme">@style/AlertDialogTheme</item>
</style>

<style name="AlertDialogTheme" parent="Theme.AppCompat.Light.Dialog.Alert">
    <item name="colorAccent">@color/accent</item>
    <item name="android:textColorPrimary">#000000</item>
</style>

<style name="EditText" parent="Widget.AppCompat.EditText">
    <item name="android:minHeight">50dp</item>
</style>

Set custom attributes on the CardEditor view in your layout:

<!-- Add xmlns:app="http://schemas.android.com/apk/res-auto" -->
<!-- to the root element of your layout to use custom attributes -->

<com.simplify.android.sdk.CardEditor
    android:id="@+id/card_editor"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:enabled="true"
    app:iconColor="@color/icon"/>

or in code:

cardEditor.setIconColor(getColor(R.color.my_custom_icon_color));
cardEditor.setEnabled(true);
simplify card editor

Android Pay

To enable Android Pay support within your app, refer to the Android Pay API tutorial. These instructions should guide you in how to:

  • Obtain a Google API key
  • Create an instance of the GoogleAPIClient
  • Incorporate the WalletFragment into your layout
  • Construct the masked and full wallet requests

Since Android Pay integration is optional with the Simplify SDK, you must provide the appropriate play services dependency.

 compile 'com.google.android.gms:play-services-wallet:9.4.0'

In order to request encrypted card information from the Android Pay wallet, you must include the Android Pay public key in the PaymentMethodTokenizationParameters. You can retrieve your public key by visiting Account Settings.

PaymentMethodTokenizationParameters parameters =
    PaymentMethodTokenizationParameters.newBuilder()
        .setPaymentMethodTokenizationType(PaymentMethodTokenizationType.NETWORK_TOKEN)
        .addParameter("publicKey", "YOUR_ANDROID_PAY_PUBLIC_KEY")
        .build();

Builder builder = MaskedWalletRequest.newBuilder();
builder.setPaymentMethodTokenizationParameters(parameters);

The Simplify SDK offers an Android Pay lifecycle handler for added convenience. You may implement the provided Android Pay callback and use the result handler within your Activity. This alleviates the need to manually handle the Android Pay activity results, and will delegate the important transaction steps to callback methods.

public class YourActivity extends Activity implements Simplify.AndroidPayCallback {

    Simplify simplify;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        // init the Simplify SDK
        simplify = new Simplify();
        simplify.setApiKey("YOUR_API_PUBLIC_KEY");
        simplify.setAndroidPayPublicKey("YOUR_ANDROID_PAY_PUBLIC_KEY");
    }

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        // delegate Android Pay transaction life-cycle to Simplify SDK
        if (simplify.handleAndroidPayResult(requestCode, resultCode, data, this)) {
            return;
        }


        // ...
    }

    //---------------------------------------------
    // Android Pay callback methods
    //---------------------------------------------

    @Override
    public void onReceivedMaskedWallet(MaskedWallet maskedWallet) {
        // ...
    }

    @Override
    public void onReceivedFullWallet(FullWallet fullWallet) {
        // ...
    }

    @Override
    public void onAndroidPayCancelled() {
        // ...
    }

    @Override
    public void onAndroidPayError(int errorCode) {
        // ...
    }

}

Once you have received your FullWallet, you may use it to create a CardToken with Simplify. Be sure to also include the Android Pay public key in this request.

simplify.createAndroidPayCardToken(fullWallet, new CardToken.Callback() {
    @Override
    public void onSuccess(CardToken cardToken) {
       // ...
    }

    @Override
    public void onError(Throwable throwable) {
       // ...
    }
});

Process a Payment

Regardless of which method you are using to collect card information, you should ultimately end up with a Simplify CardToken object. This one-time token should be sent back to your servers for processing. This is a highly recommended step to ensure your payment processing and your private API keys are kept secure.

For an example on how to start processing payments from your server, refer to https://github.com/simplifycom/simplify-php-server

Friendly reminder:
DO NOT BUNDLE YOUR PRIVATE KEY WITHIN YOUR APP!

Your private keys are considered sacred and can be used to process payments, issue refunds, and more. A common development mistake is to simply include the Java SDK in an app and use a private key to complete the transaction lifecycle without involving a server. While it may seem like an easy way to integrate payments, distributing your private key in an app leaves it vulnerable through simple reverse engineering. Once compromised, an attacker can use your key to perform almost every operation offered through our APIs. This is bad security practice. In addition, since keys can be revoked from the API Keys page, they are also considered volatile. If a private key is revoked, any app using it will be broken until an update is released with a new key. The bottom line is this: Don't do it. We will find you. :)

Rx-Enabled

If being reactive is your thing, then we've got you covered. Include the RxJava library in your project. Then, utilize the appropriate methods provided in the Simplify object.

    Single<CardToken> single = simplify.createCardToken(card);

For more information on how to set up your payment system, see the API documentation and our tutorial.