Build on Android

Applies to: In-App Payments SDK - Android | Payments API | Customers API

Learn how to build with the In-App Payments SDK on Android to provide a secure, managed payments client.

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

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

• Your application minSdkVersion is API 24 (Nougat, 7.0) or later.

• You have added the In-App-Payments SDK to your Android project. For more information, see Install In-App-Payments SDK.

• You have a Square account enabled for payment processing. If you haven't enabled payment processing on your account (or you're not sure), visit squareup.com/activation.

• You must keep the payment form open when processing payments. The In-App Payments SDK provides two ways to access the payment token depending on whether you want to keep the payment form open while processing payments. The payment processing steps in this guide assume that the form stays open. To process payments in the background, see Connect to a Backend Service for the relevant changes.

• You're generally familiar with developing applications on Android. If you're new to Android development, you should read the Getting Started Guide on the Android Developers site before continuing.

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 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((view) -> {
           CardEntry.startCardEntryActivity(CheckoutActivity.this, true, 
           DEFAULT_CARD_ENTRY_REQUEST_CODE);
       });
   }

   Note

   When testing your application in the Square Sandbox, be sure to use Sandbox test values to enter card information.

In the onActivityResult method, call the static CardEntry.handleActivityResult method with the activity results object (CardEntryActivityResult) and an anonymous method that contains your logic for responding to the card entry completion.

In the anonymous method, get a CardDetails object from the activity result and then call the getNonce() function to get the payment token.

 @Override protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    CardEntry.handleActivityResult(data, result -> {
      if (result.isSuccess()) {
        CardDetails cardResult = result.getSuccessValue();
        Card card = cardResult.getCard();
        String nonce = cardResult.getNonce();
      } else if (result.isCanceled()) {
        Toast.makeText(MainActivity.this,
            "Canceled",
            Toast.LENGTH_SHORT)
            .show();
      }
    });
  }

Declare a class that implements CardNonceBackgroundHandler to call your backend service and process the payment token 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));
    }
  }
}

The previous example refers to myBackendService, which is a placeholder for the backend service that you must create so that your application can process the payment token received from the In-App Payments SDK. The backend service calls the Payments API to create a payment that charges the card entered by a buyer in your mobile client. For more information about taking a payment, see Accept payments in your application.

When your backend service has received the payment token from your mobile application, it can take a payment but it can also use the token to store a card on file for the customer. Your mobile application must provide enough customer information for the backend to find the customer using the SearchCustomers endpoint. For example, if your mobile application has the buyer's email address and sends it to your backend along with the payment token.

To learn about how to save a card on file from your backend, see Create a Card on File and a Payment.

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

public class ExampleApplication extends Application {

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

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