Take Payments

Point of Sale API Android Setup

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

Assumptions

This guide makes the following assumptions:

The example code in this guide assumes the following:

  • You are building an Android app. For guidance on building an Android app, check our iOS Setup Guide. For guidance on building a Mobile Web app, check our Mobile Web Setup Guide.
  • You are using the Point of Sale SDK for Android version 2.0 and the Square Point of Sale v4.64 and above. The Point of Sale SDK provides a helpful wrapper around the Point of Sale API, which simplifies the development process.
  • You are using 15 as the minimum supported Android SDK version. If you are using an earlier version, you may need to update your SDK to use the sample code in this guide.
  • You are using Java. The Point of Sale SDK only supports Java on Android.
  • You using a personal access token as your authorization token. The Point of Sale API does not support sandbox at this time. Personal access tokens are appropriate for testing and development.

Step 1: Install the Square Point of Sale app

We recommend installing the latest version of the Square Point of Sale app from the Google Play Store.

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

App Version Android SDK Version
4.64 and later v2.0
4.48 and later v1.1
4.41 and later v1.0

There are 2 ways to determine the current version of the Square Point of Sale app:

adb shell dumpsys package com.squareup | grep versionName

Step 2: Register your application

The Square Point of Sale app for Android will only accept 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 app uses the SHA-1 fingerprint of an app to validate the source of incoming requests.
  • Package name (such as com.example.myapp). A Java-language-style package name for your Android app. This needs to match the name you give in the package attribute in the Android manifest for your application.

To register your application:

  1. Obtain your Android app fingerprint.
  2. Go to the Point of Sale API settings page for your application in the Application Dashboard.
  3. Under the Android section, click "Add a new Android Package".
  4. Enter your package name and fingerprint.
  5. Click "Save".

Step 3: Add the Square Point of Sale SDK to your project

Install the Point of Sale SDK manually

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

Add the Point of Sale SDK to a Gradle project

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

Android Plugin for Gradle 3.0.0+

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

Android Plugin for Gradle 2.+

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

Add the Point of Sale SDK to a Maven project

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 app

  1. Set your application ID. You can find your Application ID by opening your Application Dashboard, then clicking on an application to open the control panel.
   private static final String APPLICATION_ID = "{REPLACE ME}";
  1. Add a constructor that configures an instance of PosClient.
 1    public class MainActivity extends Activity {
 2
 3      private PosClient posClient;
 4
 5      @Override protected void onCreate(Bundle savedInstanceState) {
 6        super.onCreate(savedInstanceState);
 7        setContentView(R.layout.main_activity);
 8        // Replace APPLICATION_ID with a Square-assigned application ID
 9        posClient = PosSdk.createClient(this, APPLICATION_ID);
10        }
11    }
  1. Add code that creates a new charge request and uses it to initiate a transaction in the Point of Sale app. The function below uses ChargeRequest.Builder to create a charge for 1 USD, then uses that request to create a ChargeRequest and initiate the transaction with an Intent object.
 1// create a new charge request and initiate a Point of Sale transaction
 2    private static final int CHARGE_REQUEST_CODE = 1;
 3    public void startTransaction() {
 4      ChargeRequest request = new ChargeRequest.Builder(
 5      100,
 6      CurrencyCode.USD)
 7      .build();
 8      try {
 9        Intent intent = posClient.createChargeIntent(request);
10        startActivityForResult(intent, CHARGE_REQUEST_CODE);
11
12      } catch (ActivityNotFoundException e) {
13        AlertDialogHelper.showDialog(
14            this,
15            "Error",
16            "Square Point of Sale is not installed"
17            );
18        posClient.openPointOfSalePlayStoreListing();
19      }
20    }

Step 5: Add code to receive data from the Square Point of Sale app

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

 1  @Override protected void onActivityResult(int requestCode, int resultCode, Intent data) {
 2
 3    // Handle unexpected errors
 4    if (data == null || requestCode != CHARGE_REQUEST_CODE) {
 5        AlertDialogHelper.showDialog(this,
 6            "Error: unknown",
 7            "Square Point of Sale was uninstalled or stopped working");
 8      return;
 9    }
10
11    // Handle expected results
12    if (resultCode == Activity.RESULT_OK) {
13      // Handle success
14      ChargeRequest.Success success = posClient.parseChargeSuccess(data);
15      AlertDialogHelper.showDialog(this,
16          "Success",
17          "Client transaction ID: "
18              + success.clientTransactionId);
19    } else {
20        // Handle expected errors
21        ChargeRequest.Error error = posClient.parseChargeError(data);
22        AlertDialogHelper.showDialog(this,
23            "Error" + error.code,
24            "Client transaction ID: "
25                + error.debugDescription);
26    }
27    return;
28  }

See the Android Point of Sale API Technical Reference for more information about the ChargeRequest class.

Step 6: Test your code

  1. Log into the Square Point of Sale app with the business location you want to use to accept payments.
  2. Open your app and initiate a transaction.
  3. Test your callbacks:
    1. Test the cancellation callback: cancel the transaction.
    2. Test the success callback: complete a cash transaction.

The Square sandbox does not support credit card testing for mobile. See the Testing on Mobile guide for alternatives.

Optional: Using the Point of Sale API in offline mode

The Point of Sale API supports payment processing with the Square Point of Sale in offline mode.

To accept offline payments with the Point of Sale API:

  • Enable offline mode for the Square account taking payment.
  • Process at least 1 online transaction through the Point of Sale API every 24 hours.

Offline payment results do not include a transaction_id field, because Square's backend systems have not received and processed the transaction. Instead, the response includes a client_transaction_id field, which matches the value of client_id in Transaction objects. Use the client_transaction_id to retrieve the transaction details using the Transactions API ListTransactions endpoint once internet connection is restored and the Square Point of Sale app processes the staged transactions .

Note that it is not currently possible to filter ListTransactions results by the client_id field.

Optional: Add an alert dialog helper class

Create a dialog helper class to return an AlertDialog to show call results.

 1    import android.app.Activity;
 2    import android.app.AlertDialog;
 3    import android.app.Dialog;
 4    import android.content.pm.PackageManager;
 5    import android.os.Bundle;
 6    import android.support.v4.app.DialogFragment;
 7
 8    public class AlertDialogHelper extends DialogFragment {
 9
10      private static AlertDialog mAlertDialog;
11
12      @Override
13      public Dialog onCreateDialog(Bundle savedInstanceState) {
14        super.onCreateDialog(savedInstanceState);
15        return null;
16      }
17
18      private static Dialog getDialog(Activity activity,
19        String title, String description, int resourceId) {
20        if (mAlertDialog == null) {
21          mAlertDialog =  new AlertDialog.Builder(activity, resourceId)
22              .setTitle(title + ": " + description)
23              .setPositiveButton("OK", null)
24              .create();
25        } else {
26          mAlertDialog.setTitle(title + ":" + description);
27          mAlertDialog.setOwnerActivity(activity);
28        }
29        return mAlertDialog;
30      }
31
32      public static void showDialog(Activity activity, String title,
33         String description) {
34        int resourceId = 0;
35        try {
36          resourceId =
37              activity
38                  .getPackageManager()
39                  .getActivityInfo(activity.getComponentName()
40                      , 0)
41                  .getThemeResource();
42        } catch (PackageManager.NameNotFoundException e) {
43          e.printStackTrace();
44        } finally {
45          getDialog(
46              activity,
47              title,
48              description,
49              resourceId).show();
50        }
51      }
52    }
Prev
< Point of Sale API Overview
Next
Android Technical Reference >

Ask for help on Stack Overflow or join our Slack channel