Menu Apps
Manage Apps

Using the Point of Sale API for Android

Point of Sale API setup

Before you can begin initiating Square Point of Sale transactions from your Android app, you need to complete the following setup steps:

Enroll your application with Square

If you haven't yet, complete all of the steps in Square APIs: Getting started before you begin developing with the Point of Sale API.

Obtain your app's SHA-1 fingerprint

Square Point of Sale verifies your app's SHA-1 fingerprint to validate the transaction requests it receives.

See this article to learn how to obtain your app's SHA-1 fingerprint.

Register your app's fingerprint and package name

In order for Square Point of Sale to accept a request from your Android app, Square needs to know two values related to your app:

  • Its SHA-1 fingerprint.
  • Its package name (such as com.example.myapp). This value must match the package attribute of the manifest element in your application's Android manifest.

Go to the Point of Sale API tab of your application's settings in the application dashboard. Under the Android section, specify your app's package name and fingerprint in the corresponding fields.

Be sure to save your changes.

Add the Square Point of Sale SDK for Android to your project

Square provides an open-source SDK for you to communicate with the Square Point of Sale API from your app.

To install the SDK in a Gradle project, add the following dependency to your build.gradle and rebuild:

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

To install the SDK in a Maven project, add the following dependency to your pom.xml and rebuild:

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

The source for the SDK is available on Github.

Install the latest version of Square Point of Sale on your Android device

Square Point of Sale is available on the Google Play Store.

  • Point of Sale API v1.0 is supported in Square Point of Sale 4.41 and later.
  • Point of Sale API v1.1 is supported in Square Point of Sale 4.48 and later.
  • Point of Sale API v2.0 is supported in Square Point of Sale 4.64 and later.

To check your installed version of Point of Sale, check the FAQ.

Initiating a transaction from your app

First, create an instance of PosClient:

public class MainActivity extends Activity {

  private PosClient posClient;

  @Override protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main_activity);
    // Replace YOUR_CLIENT_ID with your Square-assigned client application ID,
    // available from the application dashboard.
    posClient = PosSdk.createClient(this, YOUR_CLIENT_ID);
  }
}

Here's how to start a one dollar transaction:

private static final int CHARGE_REQUEST_CODE = 1;
  public void startTransaction() {
    ChargeRequest request = new ChargeRequest.Builder(1_00, USD).build();
    try {
      Intent intent = posClient.createChargeIntent(request);
      startActivityForResult(intent, CHARGE_REQUEST_CODE);
    } catch (ActivityNotFoundException e) {
      showDialog("Error", "Square Point of Sale is not installed", null);
      posClient.openPointOfSalePlayStoreListing();
    }
  }

  private void showDialog(String title, String message, DialogInterface.OnClickListener listener) {
    Log.d("MainActivity", title + " " + message);
    new AlertDialog.Builder(this)
      .setTitle(title)
      .setMessage(message)
      .setPositiveButton(android.R.string.ok, listener)
      .show();
  }

As you can see above, you create a ChargeRequest.Builder to assemble the details of a Point of Sale API ChargeRequest.

SDK class descriptions

  • The Point of Sale SDK class has one purpose: you call its static createClient() method to generate a PosClient instance that you use to send charge requests along to Square Point of Sale.
  • A ChargeRequest object represents the details of a single transaction to initiate with the Point of Sale API, including the amount of money to charge. You construct a ChargeRequest object with the ChargeRequest.Builder class as shown above, calling any combination of builder methods followed by build().
  • After building a ChargeRequest, you use your PosClient instance to generate an Intent from the ChargeRequest. After you generate the Intent, you call startActivityForResult() from one of your app's activities, including the Intent as a parameter.

Complete documentation for all SDK classes and methods is available in the SDK javadoc.

Processing the transaction in Square Point of Sale

When the merchant's Android device switches over to Square Point of Sale, the details of the transaction are prepopulated. The merchant can either process the transaction with an approved payment method or cancel it. Either way, when the action completes, the device returns to your app and provides details of the result.

Receiving data from Square Point of Sale

After Square Point of Sale finishes processing a transaction (or encounters an error), it returns to your app, and the onActivityResult() method of the activity that initiated the transaction is called. Here's how to handle the response:

@Override protected void onActivityResult(int requestCode, int resultCode, Intent data) {
  super.onActivityResult(requestCode, resultCode, data);
  if (requestCode == CHARGE_REQUEST_CODE) {
    if (data == null) {
      showDialog("Error", "Square Point of Sale was uninstalled or crashed", null);
      return;
    }

    if (resultCode == Activity.RESULT_OK) {
      ChargeRequest.Success success = posClient.parseChargeSuccess(data);
      String message = "Client transaction id: " + success.clientTransactionId;
      showDialog("Success!", message, null);
    } else {
      ChargeRequest.Error error = posClient.parseChargeError(data);

      if (error.code == ChargeRequest.ErrorCode.TRANSACTION_ALREADY_IN_PROGRESS) {
        String title = "A transaction is already in progress";
        String message = "Please complete the current transaction in Point of Sale.";

        showDialog(title, message, new DialogInterface.OnClickListener() {
          @Override public void onClick(DialogInterface dialog, int which) {
            // Some errors can only be fixed by launching Point of Sale
            // from the Home screen.
            posClient.launchPointOfSale();
          }
        });
      } else {
        showDialog("Error: " + error.code, error.debugDescription, null);
      }
    }
  }
}

As shown above, the PosClient object provides separate methods for parsing a Point of Sale API response depending on whether the associated transaction succeeded or failed.

If the transaction succeeded, the ChargeRequest.Success object generated from parsing the response has the fields described here.

If the transaction failed, the ChargeRequest.Error object generated from parsing the response has the fields described here.

Error codes

If a Point of Sale API transaction fails for any reason, Square Point of Sale returns one of the error codes described here.

This value is available in the code field of the ChargeRequest.Error object you create from Square Point of Sale's response. See Receiving data from Square Point of Sale for an example.

Additional resources

Two sample Point of Sale API applications are available on Github.

If you get stuck, check if there's a solution to your issue on Stack Overflow. Questions related to Square APIs are tagged with the square-connect label and monitored by Square developers. If you can't find an answer, feel free to post a new question.

If a Square API returns an error message that is not helpful in diagnosing your issue, please contact support with the details of your issue and the error message you received.

Was this page helpful?