In-App Payments SDK

Build on Android

Build with In-App Payments SDK on Android to provide a secure, managed payments client.

Java (Android)
Android
Save

Prerequisites

To build with In-App Payments SDK on Android, the following must be true:

Assumptions

This guide makes the following assumptions:

  • You have read the In-App Payments SDK: What It Does. guide. This is a how-to guide and does not provide an overview of the SDK functionality.
  • You have a Square Account enabled for payment processing. If you have not enabled payment processing on your account (or you are not sure), visit squareup.com/activate.
  • You are generally familiar with developing apps on Android. If you are new to Android development, we recommend reading the Getting Started Guide at the Android Developers site before continuing.
  • You are building with Android Studio and Gradle. Android Studio is used because it is the most common development environment for Android apps, but In-App Payments SDK has no IDE dependency and can be used with other build methods if desired.
  • You are using Android Gradle Plugin version 3.0.0 or greater..

Step 1: Add the In-App Payments SDK dependency

  1. Add the Square SDK public repository in the build.gradle file for your project.
repositories {
   google()
   maven {
     url 'https://sdk.squareup.com/public/android'
   }
 }
  1. Add a compile option to support Java version 1.8 in the build.gradle file for your :app module.
android {
   ...

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
   ...
}
  1. Add the In-App Payments SDK dependency to the module build.gradle file.
dependencies {
  implementation "com.squareup.sdk.in-app-payments:card-entry:1.0.3"
}

Step 2: Configure the In-App Payments SDK

To configure the In-App Payments SDK, you must set the Square Application ID for your application in AndroidManifest.xml.

  1. To find your Square Application ID:
    1. Open the Square Developer Portal.
    2. Create a new Square application or select an existing application.
    3. Open the Credentials setting page for the application.
    4. Copy the Application ID field from the settings page.
  2. Open the AndroidManifest.xml file for your app gradle module and add the following XML to set the application ID.
 <?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

  <application
     ...>

    <meta-data
       android:name="sqip.SQUARE_APPLICATION_ID"
       android:value="REPLACE_WITH_YOUR_SQUARE_APPLICATION_ID"/>
  </application>
</manifest>

Step 3: Add code to collect card information and generate a nonce

Complete the following items to start the card entry flow:

  1. Set a click listener on a button.
  2. In the button click listener, call startCardEntryActivity(Activity) on CardEntry and pass a reference to the activity that starts the card entry flow.
public class CheckoutActivity extends AppCompatActivity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {

    //Find the add card button and set a click listener that starts the CardEntry activity
    sheetView.findViewById(R.id.addCardButton).setOnClickListener(v -> {
        //Start the In-App Payments CardEntry activity
        CardEntry.startCardEntryActivity(CheckoutActivity.this);
    });
}

Step 4: Get the nonce returned by the card entry screen

Get the nonce returned by CardEntry. The In-App Payments SDK provides 2 ways to access the nonce. Which method you will use depends on how you have designed the checkout flow in your app.

Checkout flow option 1

Use checkout option 1 to process payments in the background:

  • Get payment card information and close the card entry screen.
  • Confirm items to purchase and confirm card to be used.
  • Charge the payment card.

To implement the checkout flow:

  1. Override Activity.onActivityResult to get the payment card in the 2nd step of this checkout flow.
  2. Results from the card entry screen are returned as the data argument of the Activity.onActivityResult method declared in the activity that started the card entry flow. To get the card payment information, call CardEntry.handleActivityResult with the data argument from onActivityResult and a lambda expression. The lambda will only be called if data is a result coming from the card entry activity.
  3. The cardEntryActivityResult.isSuccess() method in the lambda expression returns true if the user completed payment card entry, false if they canceled.

The example below displays a success dialog:

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
       ...
            CardEntry.handleActivityResult(data, cardEntryActivityResult -> {
                if (cardEntryActivityResult.isSuccess()) {
                 CardDetails cardDetails = cardEntryActivityResult.getSuccessValue();
                 String successMessage = "Card to be charged: " + cardDetails.toString()

                  new AlertDialog.Builder(this)
                    .setTitle(R.string.success_title)
                    .setMessage(successMessage)
                    .setPositiveButton(R.string.ok, null)
                    .show();
                }
            });
      ...
    }

Checkout flow option 2

Use checkout option 2 to process payments while the card entry screen is visible:

  • Confirm items to purchase and confirm card to be used.
  • Get payment card information and close the card entry screen.
  • Wait until the payment card is charged to continue.

To implement the checkout flow:

  1. Declare a class that implements CardNonceBackgroundHandler to call your backend service and process the nonce while the payment form is still open. The background handler lets you process a nonce and complete a payment flow.
    public class CardEntryBackgroundHandler implements CardNonceBackgroundHandler {
  @Override
  public CardEntryActivityCommand handleEnteredCardInBackground(CardDetails cardDetails) {
    try {
      // TODO Call your backend service
      MyBackendServiceResponse response = ...
      if (response.isSuccessful()) {
         return new CardEntryActivityCommand.Finish();
            } else {
         return new CardEntryActivityCommand.ShowError(response.errorMessage)
      }
    } catch(IOException exception) {
       return new CardEntryActivityCommand.ShowError(
             resources.getString(R.string.network_failure));
    }
  }
}
  1. In your application class, set the CardEntry.cardNonceBackgroundHandlerto a reference to the CardEntryBackgroundHandler.
public class ExampleApplication extends Application {
  private ChargeCall.Factory chargeCallFactory;

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

    CardEntryBackgroundHandler cardHandler =
        new CardEntryBackgroundHandler();
    CardEntry.setCardNonceBackgroundHandler(cardHandler);
  }
}

Optional: Set an application ID at runtime

If you want to set the application ID programmatically at runtime, call the following code before calling the startCardEntryActivity method on CardEntry.

 InAppPaymentsSdk.setSquareApplicationId(REPLACE_WITH_AN_APPLICATION_ID);

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow