In-App Payments SDK

Build on Android

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

Android
UI
In-App Payments SDK

Prerequisites and assumptions
Permalink Get a link to this section

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

  • Your application minSdkVersion is API 21 (Lollipop, 5.0) or higher.

  • You have added the In-App-Payments SDK to your Android project. See Installing In-App-Payments SDK for more information.

  • 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.


Additionally, this guide makes the following assumptions:

  • You will keep the payment form open when processing payments. The In-App Payments SDK provides 2 ways to access the nonce depending on whether or not you want to keep the payment form open while processing payments. The payment processing steps in this guide assume the form will stay open. To process payments in the background, see the Connect to a Backend Service recipe for the relevant changes.

  • 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.

Important

While In-App Payments SDK supports payment processing for physical and digital sales, using In-App Payments SDK to process digital sales may not be allowed by some mobile application distribution services (e.g., App Store, Google Play) and may result in your application being removed. Examples of digital sales include: intangible goods (e.g., in-game assets), online services (e.g., upgrades in app functionality), and digital subscriptions (e.g., cloud or streaming services).

To avoid potential removal from application distribution platforms, In-App Payments SDK should only be used to process sales of goods or services that will be consumed outside of the app. We recommend that you review the terms of service for the respective mobile application distribution services you use to ensure you are compliant with their guidelines.

Step 1: Add code to collect card information and generate a nonce
Permalink Get a link to this section

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);
    });
}

Note

When testing your app in the v2 Sandbox (beta), be sure to use sandbox test values to input card information.

Step 2: Process the nonce
Permalink Get a link to this section

Declare a class that implements CardNonceBackgroundHandler to call your backend service and process the nonce while the payment form is still open:


public class CardEntryBackgroundHandler implements CardNonceBackgroundHandler {
  @Override
  public CardEntryActivityCommand handleEnteredCardInBackground(CardDetails cardDetails) {
    try {
      // TODO Call your backend service
      MyBackendServiceResponse response = // myBackendService(cardDetails.getNonce());...
            
      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));
    }
  }
}

Step 3: Set the CardEntry background handler
Permalink Get a link to this section

In your application class, set the CardEntry.cardNonceBackgroundHandler to reference the CardEntryBackgroundHandler.

Important

The CardEntryBackgroundHandler must be set in the application class so that it is set again if the app process is stoppped and later restarted on the card entry flow.

public class ExampleApplication extends Application {

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

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

Next steps

Now that you have a basic build in place, expand on it with these recipes!