Point of Sale API

Build on Android

Open the Square Point of Sale application from your mobile Android application to process in-person payments using Square hardware.

Prerequisites and assumptions Permalink Get a link to this section

This guide makes the following assumptions:

  • You have read the What It Does topic for this product.

The example code in this guide assumes the following:

  • You are building an Android application. For information about building an iOS application, see Build on iOS. For information about building a Mobile Web application, see Build on Mobile Web.

  • You are using Point of Sale SDK for Android version 2.0 and the Square Point of Sale application v4.64 and later. Point of Sale SDK provides a helpful wrapper around the Point of Sale API, which simplifies the development process.

  • You are using version 15 as the minimum supported Android SDK version. If you are using an earlier version, you might need to update your SDK to use the sample code in this guide.

  • You are using Java. Point of Sale SDK only supports Java on Android.

Information you need Permalink Get a link to this section

To use the steps in this topic, you need:

Step 1: Install the Square Point of Sale application Permalink Get a link to this section

You should install the latest version of the Square Point of Sale application from the Google Play Store.

If you choose to use an older version of the Point of Sale application, you need to confirm that the version is compatible with the Android Point of Sale SDK version you are using:

Application versionAndroid SDK version
4.64 and laterv2.0
4.48 and laterv1.
4.41 and laterv1.0

There are two ways to determine the current version of the Square Point of Sale application:

  • Look it up in the device settings.

  • Run the following command using ADB:

    adb shell dumpsys package com.squareup | grep versionName
    

Step 2: Register your application Permalink Get a link to this section

The Square Point of Sale application for Android only accepts requests if it can authenticate the source of the request. Square uses the following information to authenticate application requests:

  • SHA-1 fingerprint. The Square Point of Sale application uses the SHA-1 fingerprint of an application to validate the source of incoming requests.

  • Package name (such as com.example.myapp). A Java-language-style package name for your Android application. This needs to match the name you use in the package attribute in the Android manifest for your application.

To register your application:

  1. Obtain your Android application fingerprint.

  2. Go to the Point of Sale API settings page for your application in the Developer Dashboard.

  3. In the Android section, choose Add a new Android Package.

  4. Enter your package name and fingerprint.

  5. Choose Save.

Step 3: Add Square Point of Sale SDK to your project Permalink Get a link to this section

Install Point of Sale SDK manually Permalink Get a link to this section

To install Point of Sale SDK manually, download the point-of-sale-android-sdk repo on Github.

Add Point of Sale SDK to a Gradle project Permalink Get a link to this section

If you develop with Gradle, add the following dependency that is appropriate for your plugin to your build.gradle file and rebuild your project.

Android plugin for Gradle 3.0.0 and later Permalink Get a link to this section

dependencies {
  implementation 'com.squareup.sdk:point-of-sale-sdk:2.+'
}

Android plugin for Gradle 2 and later Permalink Get a link to this section

dependencies {
  compile 'com.squareup.sdk:point-of-sale-sdk:2.+'
}

Add Point of Sale SDK to a Maven project Permalink Get a link to this section

If you develop with Maven, add the following dependency to your pom.xml file and rebuild your project:

<dependency>
  <groupId>com.squareup.sdk</groupId>
  <artifactId>point-of-sale-sdk</artifactId>
  <version>2.0</version>
  <type>aar</type>
</dependency>

Step 4: Add code to initiate a transaction from your application Permalink Get a link to this section

  1. Set your application ID. To find your application ID, open the Developer Dashboard, and choose an application.

  2. Add a constructor that configures an instance of PosClient.

  3. Add code that creates a new charge request and uses it to initiate a transaction in the Point of Sale application. The following function uses ChargeRequest.Builder to create a charge for $1 USD and then uses that request to create a ChargeRequest and initiate the transaction with an Intent object.

Set your application ID as shown:

   private static final String APPLICATION_ID = "{REPLACE ME}";

Add a constructor as shown:

    public class MainActivity extends Activity {

      private PosClient posClient;

      @Override protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main_activity);
        // Replace APPLICATION_ID with a Square-assigned application ID
        posClient = PosSdk.createClient(this, APPLICATION_ID);
        }
    }

Create a new charge request as shown:

// create a new charge request and initiate a Point of Sale transaction
    private static final int CHARGE_REQUEST_CODE = 1;
    public void startTransaction() {
      ChargeRequest request = new ChargeRequest.Builder(
      100,
      CurrencyCode.USD)
      .build();
      try {
        Intent intent = posClient.createChargeIntent(request);
        startActivityForResult(intent, CHARGE_REQUEST_CODE);

      } catch (ActivityNotFoundException e) {
        AlertDialogHelper.showDialog(
            this,
            "Error",
            "Square Point of Sale is not installed"
            );
        posClient.openPointOfSalePlayStoreListing();
      }
    }

Note

The AlertDialogHelper object that is used in the step 4 and step 5 code blocks is an example of a helper class instance and not part of Point of Sale SDK.

Step 5: Add code to receive data from the Square Point of Sale application Permalink Get a link to this section

When the Square Point of Sale application completes a transaction (or encounters an error), it returns the UI focus to your application and calls the onActivityResult() method of the activity that initiated the transaction. Add code to parse the response.


  @Override protected void onActivityResult(int requestCode, int resultCode, Intent data) {

    // Handle unexpected errors
    if (data == null || requestCode != CHARGE_REQUEST_CODE) {
        AlertDialogHelper.showDialog(this,
            "Error: unknown",
            "Square Point of Sale was uninstalled or stopped working");
      return;
    }

    // Handle expected results
    if (resultCode == Activity.RESULT_OK) {
      // Handle success
      ChargeRequest.Success success = posClient.parseChargeSuccess(data);
      AlertDialogHelper.showDialog(this,
          "Success",
          "Client transaction ID: "
              + success.clientTransactionId);
    } else {
        // Handle expected errors
        ChargeRequest.Error error = posClient.parseChargeError(data);
        AlertDialogHelper.showDialog(this,
            "Error" + error.code,
            "Client transaction ID: "
                + error.debugDescription);
    }
    return;
  }

For more information about the ChargeRequest class, see the Android Point of Sale API Technical Reference.

Did you know?

Your application should keep track of whether a Point of Sale API request has been issued and whether a callback has been received. Because of the constraints of application-switching APIs, sellers can leave Square Point of Sale during an API request and return to your application. It is your responsibility to direct them to return to Square and finish the transaction.

Step 6: Test your code Permalink Get a link to this section

  1. Sign in to the Square Point of Sale application with the business location that you want to use to accept payments.

  2. Open your application and initiate a transaction.

  3. Test your callbacks:

    • Test the cancellation callback by canceling a transaction.

    • Test the success callback by completing a cash transaction.

The Sandbox does not support credit card testing for mobile. For alternatives, see Test Mobile Applications.

Related topics Permalink Get a link to this section