In-App Payments SDK

Build on Android

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

  • You have added 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 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 keep the payment form open when processing payments. In-App Payments SDK provides two ways to access the nonce 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 are generally familiar with developing applications on Android. If you are new to Android development, you should read the Getting Started Guide at the Android Developers site before continuing.

    Important

    While In-App Payments SDK supports payments for physical and digital sales, using 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, 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 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.

Register the activity onActivityResult as a callback Permalink Get a link to this section

  1. Set a click listener on a button.

  2. In the button click listener, call startCardEntryActivity(Activity activity, boolean collectPostalCode, int requestCode) 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.

Get the card nonce in the activity result Permalink Get a link to this section

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

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

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 CardEntry.cardNonceBackgroundHandler to reference CardEntryBackgroundHandler.

Important

The CardEntryBackgroundHandler must be set in the application class so that it is set again if the application process is stopped 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);
  }
}