Reader SDK

Build on Android

Build a secure in-person payment solution for Android devices with the Reader SDK.

Prerequisites and assumptions
Device compatibility
Information you need
Step 1: Request Reader SDK credentials
Step 2: Configure Gradle for the Reader SDK
Step 3: Configure the build dependencies
Step 4: Extend the Android Application class
Step 5: Add code to request and use a mobile authorization code
Step 6: Add code to handle authorization results
Step 7: Create a CheckoutActivity
Step 8: Add code to start the checkout flow
Step 9: Add code to handle checkout results
See also

Link to section
Prerequisites and assumptions

To build with the Reader SDK, the following must be true:

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.
Your application minSdkVersion is API 24 (Android 7) or later.
Your application targetSdkVersion is API 33 (Android 13) or earlier.
Your application compileSdkVersion is 32.
Your application uses AndroidX or enables Jetifier in gradle.properties.
You're using the Android Gradle Plugin version 3.0.0 or later. The Reader SDK might work with 2.3.0 or later, but stability isn't guaranteed.
Your application uses Google Play Services version 16.0.1. Square cannot guarantee that the SDK works with different versions of these libraries.
You're not using Proguard for code optimization. Compressing the Reader SDK binary removes critical bytecode elements and results in runtime errors.

Additionally, this guide makes the following assumptions:

Your version of the Reader SDK adheres to the Square update policy. To limit risk to developers and their users, Square enforces a Reader SDK update policy requiring developers keep their version of the Reader SDK current.
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.

Important

The Reader SDK isn't supported on Android versions earlier than API 19 (Android 4.4).

Link to section
Device permissions

To work with Square Readers, applications must have the following device permissions. If the required device permissions aren't granted when the checkout flow initiates, the Reader SDK prompts the user to grant the necessary permissions.

Android device permission	Purpose
Location	To confirm that payments are occurring in a supported country.
Audio	To connect Magstripe Readers.
Bluetooth	To connect Contactless Readers.
Device Storage	To store information during checkout.
Phone Access	To identify the device sending information to Square servers.

Link to section
Device compatibility

The Reader SDK isn't compatible to run on custom devices from OEMs that violate Square's security rules or on devices that grant root access to the mobile device operating system code and kernel. As a result, these devices cannot connect to a Contactless and Chip Reader.

The following additional considerations apply when trying to run the SDK on custom devices:

The Reader SDK cannot run on custom operating systems.
The Reader SDK isn't supported to run on rooted or jailbroken devices.
Square prohibits using any software that provides the ability to record or capture screen data or that results in elevated privileges.
Square recommends running the Reader SDK on devices from large mobile device manufacturers such as Google, Samsung, or HTC.
Avoid running on devices from smaller OEMs because there's no guarantee that they comply with Square's required security standards.
Verify that your device is supported (see Devices Compatible with the Square Magstripe and Chip Card Readers).
Supported OS versions should be the latest or as close to the latest as possible.
Review Square's support window for the OS version and confirm support for the compilation target version and the runtime version: The compilation target currently supports versions 21 to 30. For runtime, the supported versions are 21 to 31.

If the mobile application runs on an uncommon device manufacturer, be sure to test connecting to the Square Reader over Bluetooth before investing in the device.

The following steps are recommended to verify your device:

Test the device with any expected software requirements before committing to using it for the Reader SDK.
Review Square's version support window.
Ensure that you can pair the device with the Reader SDK using Bluetooth.

Link to section
Information you need

To use the steps in this topic, you need the following:

Your application ID - Find your application ID on the Credentials page of your Square application in the Developer Dashboard.
Your Reader SDK repository password - Find your Reader SDK repository password on the Reader SDK page of your Square application in the Developer Dashboard.

Link to section
Step 1: Request Reader SDK credentials

Open the Developer Dashboard. You're prompted to sign in or create an account.
Create a Square application.
Choose the new application to open the Square application settings pages.
Open the Reader SDK page, and then choose Request Credentials to generate your Reader SDK repository password.

Link to section
Step 2: Configure Gradle for the Reader SDK

Update the gradle.properties file in the root folder of your project to increase the maximum heap size provided to the Gradle daemon and set variables for the Square application ID and repository password.

Add the Reader SDK variables from your properties file and confirm that the Google repository is set properly in the build.gradle file of your :app module.

a. Update the gradle.properties file.

SQUARE_READER_SDK_APPLICATION_ID={APPLICATION ID FROM STEP 1}
SQUARE_READER_SDK_REPOSITORY_PASSWORD={REPO PASSWORD FROM STEP 1}
org.gradle.jvmargs=-Xmx4g

b. Add the Reader SDK variables.

1
2
3
4
5
6
7
8
9
10
11

 repositories {
  google()
  maven {
    url "https://sdk.squareup.com/android"
    credentials {
      username SQUARE_READER_SDK_APPLICATION_ID
      password SQUARE_READER_SDK_REPOSITORY_PASSWORD
    }
  }
  mavenCentral()
}

Link to section
Step 3: Configure the build dependencies

If you run into compile errors, make sure that you're using AndroidX across all your dependencies by running ./gradlew app:dependencies.

The Reader SDK and its dependencies contain more than 65,000 methods, so your build script must enable multidex. If your minSdkVersion is earlier than API 21, you need to include the multidex dependency.

Connect the Reader SDK to a Square Contactless Reader to accept chip and tap payments.

1
2
3
4
5
6
7
8
9
10
11
12
13

android {
  defaultConfig {
    minSdkVersion 21
    targetSdkVersion 31
    multiDexEnabled true
  }
}

dependencies {
  // Add this dependency if your minSdkVersion < 21
  implementation 'androidx.multidex:multidex:2.0.0'
  // ...
}

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
  }
  // ...
}

Configure the multidex options.

1
2
3
4
5
6
7
8
9
10
11
12

android {
  // ...
  dexOptions {
    // Ensures incremental builds remain fast
    preDexLibraries true
    // Required to build with Reader SDK
    jumboMode true
    // Required to build with Reader SDK
    keepRuntimeAnnotatedClasses false
  }
  // ...
}

Add the Reader SDK dependencies.

dependencies {
  def readerSdkVersion = "1.7.4"
  implementation "com.squareup.sdk.reader:reader-sdk-$SQUARE_READER_SDK_APPLICATION_ID:$readerSdkVersion"
  runtimeOnly "com.squareup.sdk.reader:reader-sdk-internals:$readerSdkVersion"
  // ...
}

Link to section
Step 4: Extend the Android Application class

Create an Application class that extends android.app.Application and specify the android:name property for the <application> node in AndroidManifest.xml. For more information, see Understanding the Android Application Class on Codepath.

Import and initialize the Reader SDK.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

import com.squareup.sdk.reader.ReaderSdk;
import com.squareup.sdk.reader.authorization.AuthorizationManager;
import com.squareup.sdk.reader.authorization.AuthorizeErrorCode;
import com.squareup.sdk.reader.authorization.Location;
import com.squareup.sdk.reader.core.CallbackReference;
import com.squareup.sdk.reader.core.Result;
import com.squareup.sdk.reader.core.ResultError;

public class ExampleApplication extends Application {

  @Override public void onCreate() {
    super.onCreate();
    ReaderSdk.initialize(this);
   }

  @Override protected void attachBaseContext(Context base) {
    super.attachBaseContext(base);
    // Required if minSdkVersion < 21
    MultiDex.install(this);
  }
}

Link to section
Step 5: Add code to request and use a mobile authorization code

To authorize the SDK, you must build an authorization service to retrieve a mobile authorization code with the Mobile Authorization API and return it to your application.

Mobile authorization codes are short lived and should be used immediately to authorize the Reader SDK. Authorization is valid until it's explicitly revoked by calling deauthorize or your application fails to take a payment within 90 days. Mobile authorization codes don't need to be manually refreshed under normal operations.

Create a new AuthorizeActivity with two skeleton functions (retrieveAuthorizationCode() and onAuthorizationCodeRetrieved()), and then customize them to call your authorization service.

You can also generate mobile authorization codes manually with a command-line tool. For more information, see Request a Mobile Authorization Code on the Command Line.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

public class AuthorizeActivity extends Activity {

  @Override protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    setContentView(R.layout.authorize_activity);

    View authorizeButton = findViewById(R.id.authorize_button);
    authorizeButton.setOnClickListener(view -> retrieveAuthorizationCode());
  }

  private void retrieveAuthorizationCode() {
    // TODO: Asynchronous code to retrieve a mobile authorization code.
    // Calls onAuthorizationCodeRetrieved(String) with the resulting code.
  }

  private void onAuthorizationCodeRetrieved(String authorizationCode) {
    showAuthorizationInProgress(true);
    ReaderSdk.authorizationManager().authorize(authorizationCode);
  }

  private void showAuthorizationInProgress(boolean inProgress) {
    // TODO: Display or hide a loading indicator
  }
}

Link to section
Step 6: Add code to handle authorization results

Add a callback (onAuthorizeResult()) to the Authorization Manager in the onCreate method of your authorization activity using AuthorizationManager.addAuthorizeCallback().
Implement the onAuthorizeResult() callback. AuthorizeCallback.onResult() is invoked asynchronously on the main thread with a Result object. The result includes the authorized Location (in case of success) or a ResultError (in case of error).
Add code to clear the callback reference in your onDestroy() method to avoid memory leaks.

Add the onAuthorizeResult callback to the Authorization Manager.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

//
public class AuthorizeActivity extends Activity {

  // ...

  private CallbackReference authorizeCallbackRef;

  @Override protected void onCreate(Bundle savedInstanceState) {

    //...

    AuthorizationManager authManager = ReaderSdk.authorizationManager();
authorizeCallbackRef =
        authManager.addAuthorizeCallback(this::onAuthorizeResult  );
  }

  // ...

  private void onAuthorizeResult(Result<Location,
      ResultError<AuthorizeErrorCode>> result) {
    // TODO: Handle the authorization result
  }

Implement the onAuthorizeResult() callback.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

  private void onAuthorizeResult(Result<Location,
      ResultError<AuthorizeErrorCode>> result) {
    showAuthorizationInProgress(false);
    if (result.isSuccess()) {
      goToCheckoutActivity();
    } else {
      ResultError<AuthorizeErrorCode> error = result.getError();
      switch (error.getCode()) {
        case NO_NETWORK:
          showDialog(getString(R.string.no_network), error.getMessage());
          break;
        case USAGE_ERROR:
          String dialogMessage = error.getMessage();
          if (BuildConfig.DEBUG) {
            dialogMessage += "\n\nDebug Message: " + error.getDebugMessage();
            Log.d("Auth", error.getDebugCode() + ", " + error.getDebugMessage());
          }
              showDialog(getString(R.string.error_dialog_title), dialogMessage);
          break;
      }
    }
 }

Clear the callback reference in your onDestroy() method.

public class AuthorizeActivity extends Activity {

  // ...

  @Override protected void onDestroy() {
    super.onDestroy();
    authorizeCallbackRef.clear();
  }
}

Link to section
Step 7: Create a CheckoutActivity

Create a new activity, CheckoutActivity, with a button that calls startCheckout() to begin the checkout flow.

The Checkout activity is a good place to add a button that starts the contactless reader connect flow. A Square contactless reader cannot be connected until the Reader SDK is authorized. Authorization is completed in step 6, which means you can now connect a reader. For information about connecting a reader, see Connect a Contactless Reader.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

import com.squareup.sdk.reader.checkout.AdditionalPaymentType;
import com.squareup.sdk.reader.checkout.CheckoutErrorCode;
import com.squareup.sdk.reader.checkout.CheckoutManager;
import com.squareup.sdk.reader.checkout.CheckoutParameters;
import com.squareup.sdk.reader.checkout.CheckoutResult;
import com.squareup.sdk.reader.checkout.CurrencyCode;
import com.squareup.sdk.reader.checkout.Money;
import com.squareup.sdk.reader.core.CallbackReference;
import com.squareup.sdk.reader.core.Result;
import com.squareup.sdk.reader.core.ResultError;

public class CheckoutActivity extends Activity {

  @Override protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    if (!ReaderSdk.authorizationManager().getAuthorizationState().isAuthorized()) {
      goToAuthorizeActivity();
    }

    setContentView(R.layout.checkout_activity);

    View startCheckoutButton = findViewById(R.id.start_checkout_button);
    startCheckoutButton.setOnClickListener(view -> startCheckout());
  }

  private void goToAuthorizeActivity() {
      // TODO: Reader SDK is not authorized, move to Authorize Activity
  }
}

Link to section
Step 8: Add code to start the checkout flow

Implement the startCheckout() method by adding code to build the CheckoutParameters object and configure the checkout experience. The following code uses CurrencyCode#current to obtain the currency code of the authorized location and set CASH as one of the additional tender types, which lets you test payments without charging a card.
Add a callback (onCheckoutResult()) to the Checkout Manager in the onCreate method of CheckoutActivity using CheckoutManager.addCheckoutActivityCallback.
Add code to clear the checkout callback reference in your onDestroy() method to avoid memory leaks.

Implement the startCheckout() method.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

public class CheckoutActivity extends Activity {
  // ...

  private CallbackReference checkoutCallbackRef;

  private void startCheckout() {
    CheckoutManager checkoutManager =     ReaderSdk.checkoutManager();
    Money amountMoney = new Money(100,     CurrencyCode.current());
    CheckoutParameters.Builder parametersBuilder =
        CheckoutParameters.newBuilder(amountMoney);
    if (BuildConfig.DEBUG) {
     parametersBuilder.additionalPaymentTypes(AdditionalPaymentType.CASH);
    }
    checkoutManager.startCheckoutActivity(this, parametersBuilder.build());
  }
}

Add onCheckoutResult() to the Checkout Manager.

1
2
3
4
5
6
7
8
9
10

  @Override protected void onCreate(Bundle savedInstanceState) {

    // ...

    CheckoutManager checkoutManager = ReaderSdk.checkoutManager();
    checkoutCallbackRef =   
        checkoutManager.addCheckoutActivityCallback(this::onCheckoutResult);

  }
}

Clear the checkout callback reference in your onDestroy() method.

public class CheckoutActivity extends Activity {

  // ...

    @Override protected void onDestroy() {
    super.onDestroy();
    checkoutCallbackRef.clear();
  }
}

Link to section
Step 9: Add code to handle checkout results

Implement the onCheckoutResult callback to parse the checkout response. CheckoutActivityCallback.onResult() is invoked asynchronously on the main thread with a Result object. The result includes the CheckoutResult (in case of success) or a ResultError (in case of error).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

public class CheckoutActivity extends Activity {
  // ...

  private void onCheckoutResult(Result<CheckoutResult, ResultError<CheckoutErrorCode>> result) {
    if (result.isSuccess()) {
      CheckoutResult checkoutResult = result.getSuccessValue();
      showCheckoutResult(checkoutResult);
    } else {
      ResultError<CheckoutErrorCode> error = result.getError();

      switch (error.getCode()) {
        case SDK_NOT_AUTHORIZED:
          goToAuthorizeActivity();
          break;
        case CANCELED:
          Toast.makeText(this, "Checkout canceled", Toast.LENGTH_SHORT).show();
          break;
        case USAGE_ERROR:
          showErrorDialog(error);
          break;
      }
    }
  }

  private void showCheckoutResult(CheckoutResult checkoutResult) {
    // TODO: Display the checkout result.
  }

  private void showErrorDialog(ResultError<?> error) {
    String dialogMessage = error.getMessage();
    if (BuildConfig.DEBUG) {
      dialogMessage += "\n\nDebug Message: " + error.getDebugMessage();
      Log.d("Checkout", error.getDebugCode() + ", " + error.getDebugMessage());
    }
    showDialog(getString(R.string.error_dialog_title), dialogMessage);
  }

  private void showDialog(CharSequence title, CharSequence message) {
    // TODO: Display a dialog to the user.
  }
}

Link to section
See also

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Docs

Build on Android

On this page

Link to section
Prerequisites and assumptions

Important

Link to section
Device permissions

Link to section
Device compatibility

Link to section
Information you need

Link to section
Step 1: Request Reader SDK credentials

Link to section
Step 2: Configure Gradle for the Reader SDK

Link to section
Step 3: Configure the build dependencies

Did you know?

Link to section
Step 4: Extend the Android Application class

Link to section
Step 5: Add code to request and use a mobile authorization code

Did you know?

Link to section
Step 6: Add code to handle authorization results

Link to section
Step 7: Create a CheckoutActivity

Did you know?

Link to section
Step 8: Add code to start the checkout flow

Link to section
Step 9: Add code to handle checkout results

Link to section
See also

On this page

Docs

Build on Android

On this page

Link to section Prerequisites and assumptions

Important

Link to section Device permissions

Link to section Device compatibility

Link to section Information you need

Link to section Step 1: Request Reader SDK credentials

Link to section Step 2: Configure Gradle for the Reader SDK

Link to section Step 3: Configure the build dependencies

Did you know?

Link to section Step 4: Extend the Android Application class

Link to section Step 5: Add code to request and use a mobile authorization code

Did you know?

Link to section Step 6: Add code to handle authorization results

Link to section Step 7: Create a CheckoutActivity

Did you know?

Link to section Step 8: Add code to start the checkout flow

Link to section Step 9: Add code to handle checkout results

Link to section See also

On this page

Link to section
Prerequisites and assumptions

Link to section
Device permissions

Link to section
Device compatibility

Link to section
Information you need

Link to section
Step 1: Request Reader SDK credentials

Link to section
Step 2: Configure Gradle for the Reader SDK

Link to section
Step 3: Configure the build dependencies

Link to section
Step 4: Extend the Android Application class

Link to section
Step 5: Add code to request and use a mobile authorization code

Link to section
Step 6: Add code to handle authorization results

Link to section
Step 7: Create a CheckoutActivity

Link to section
Step 8: Add code to start the checkout flow

Link to section
Step 9: Add code to handle checkout results

Link to section
See also