Menu Apps

Using the Web API for Android

Web API setup

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

Enroll your application with Square

If you haven't yet, complete steps 1 & 2 in Square APIs: Getting Started before you begin developing with the Web API.

Register your web callback URI

In order for Square Point of Sale to accept a request from your website, Square needs to verify that you have registered a web callback URI for the application in the Square developer portal.

First, go to the application dashboard, then click on the Point of Sale API tab of your application's settings. Under the Web section, specify your app's web callback URI under the corresponding field.

Be sure to save your changes.

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

Square Point of Sale is available on the Google Play Store. Web API is supported in Square Point of Sale 4.54 and later.

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

Initiating a transaction from your website

To initiate a transaction from your website, you supply a specially-crafted link or button similar to the following to direct the user to Square Point of Sale.

Here's an example that starts a one dollar transaction:

<a href="intent:#Intent;action=com.squareup.pos.action.CHARGE;package=com.squareup;S.browser_fallback_url=https://my.website.com/index.html;S.com.squareup.pos.WEB_CALLBACK_URI=https://my.website.com/index.html;S.com.squareup.pos.CLIENT_ID=sq0ids-yOurCLieNtId;S.com.squareup.pos.API_VERSION=v2.0;i.com.squareup.pos.TOTAL_AMOUNT=100;S.com.squareup.pos.CURRENCY_CODE=USD;S.com.squareup.pos.TENDER_TYPES=com.squareup.pos.TENDER_CARD,com.squareup.pos.TENDER_CARD_ON_FILE,com.squareup.pos.TENDER_CASH,com.squareup.pos.TENDER_OTHER;end">Send me $</a>

Notice that a list of key-value pairs delimited with semicolons and wrapped by special Android start and end tokens, intent:#Intent; and end, is embedded in the target URL.

Name Description
action Required. This must be com.squareup.pos.action.CHARGE. This represents a Square transaction request.
S.com.squareup.pos.WEB_CALLBACK_URI Required. The callback URI that Square Point of Sale will use to send a response
S.com.squareup.pos.CLIENT_ID Required. Your client ID
S.com.squareup.pos.API_VERSION Required. The targeted version of the Square Point of Sale API, e.g., v2.0
S.com.squareup.pos.CURRENCY_CODE Required. The currency code, e.g., USD
i.com.squareup.pos.TOTAL_AMOUNT Required. The total amount represented in the smallest unit of the supplied currency, e.g., a value of 100 corresponds to $1.00 USD
S.com.squareup.pos.TENDER_TYPES Required. Provides the tender types that will be allowed and displayed by Square Point of Sale. Must be a non-empty comma-delimited set of the following:
  • com.squareup.pos.TENDER_CARD
  • com.squareup.pos.TENDER_CARD_ON_FILE
  • com.squareup.pos.TENDER_CASH
  • com.squareup.pos.TENDER_OTHER
package Recommended. If set, this must be 'com.squareup'. Identifies the package name of the application responding to this intent.
S.browser_fallback_url Optional. If Point of Sale is not installed, Android will route to this supplied url; If missing, Android will route to Play Store if package parameter is provided.
S.com.squareup.pos.NOTE Optional. A note to add to your transaction if completed successfully.
S.com.squareup.pos.REQUEST_METADATA Optional. The state parameter that is returned in the response for the developer's use.

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 pre-populated. 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 website 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 website using the web callback URI you supplied in the URL target.

You can parse the query parameters of the URI to determine whether the associated transaction succeeded or failed along with its accompanying metadata.

If the transaction succeeded, the response will have the following parameters:

  • com.squareup.pos.CLIENT_TRANSACTION_ID
  • com.squareup.pos.SERVER_TRANSACTION_ID (if processing a card transaction online)

If the transaction failed, the response will have the following parameters:

  • com.squareup.pos.ERROR_CODE
  • com.squareup.pos.ERROR_DESCRIPTION

In both success and error cases, the response will also include com.squareup.pos.RESULT_REQUEST_METADATA, if supplied by the developer.

Error codes

If a Point of Sale API transaction fails for any reason, Square Point of Sale returns an error code as the value of the com.squareup.pos.ERROR_CODE query parameter in the response.

Here is a table of the possible error codes:

CUSTOMER_MANAGEMENT_NOT_SUPPORTED The merchant account does not support Customer Management.
DISABLED The Point of Sale API is not currently available.
ILLEGAL_LOCATION_ID The provided location ID does not correspond to the location currently logged in to Square Point of Sale.
INVALID_CUSTOMER_ID The provided customer ID is invalid.
INVALID_REQUEST The information provided in this transaction request is invalid (e.g., a required field is missing or malformed).
NO_EMPLOYEE_LOGGED_IN Employee management is enabled but no employee is logged in to Square Point of Sale.
NO_NETWORK Square Point of Sale was unable to validate the Point of Sale API request because the Android device did not have an active network connection.
NO_RESULT Square Point of Sale did not return a transaction result.
TRANSACTION_ALREADY_IN_PROGRESS Another Square Point of Sale transaction is already in progress.
TRANSACTION_CANCELED The merchant canceled the transaction.
UNAUTHORIZED_CLIENT_ID The application with the provided client ID is not authorized to use the Point of Sale API.
UNEXPECTED An unexpected error occurred.
UNSUPPORTED_API_VERSION The installed version of Square Point of Sale doesn't support this version of the Point of Sale SDK.
UNSUPPORTED_WEB_API_VERSION Web API is not supported in the supplied API version (must be >= v1.3).
USER_NOT_ACTIVATED The merchant tried to process the transaction with a credit card, but the merchant's Square account has not yet been activated for card processing.
USER_NOT_LOGGED_IN No user is currently logged in to Square Point of Sale.

Additional resources

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?