Menu Apps
Manage Apps

Using the Web API for Android

Web API setup

Before you can begin initiating Square Register 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 Register 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 Register 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 Register on your Android device

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

To check your installed version of Register, 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 Register.

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

<a href="intent:#Intent;action=com.squareup.register.action.CHARGE;package=com.squareup;S.browser_fallback_url=https://my.website.com/index.html;S.com.squareup.register.WEB_CALLBACK_URI=https://my.website.com/index.html;S.com.squareup.register.CLIENT_ID=sq0ids-yOurCLieNtId;S.com.squareup.register.API_VERSION=v1.3;i.com.squareup.register.TOTAL_AMOUNT=100;S.com.squareup.register.CURRENCY_CODE=USD;S.com.squareup.register.TENDER_TYPES=com.squareup.register.TENDER_CARD,com.squareup.register.TENDER_CARD_ON_FILE,com.squareup.register.TENDER_CASH,com.squareup.register.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.register.action.CHARGE. This represents a Square transaction request.
S.com.squareup.register.WEB_CALLBACK_URI Required. The callback URI that Square Register will use to send a response
S.com.squareup.register.CLIENT_ID Required. Your client ID
S.com.squareup.register.API_VERSION Required. The targeted version of the Square Register API, e.g., v1.3
S.com.squareup.register.CURRENCY_CODE Required. The currency code, e.g., USD
i.com.squareup.register.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.register.TENDER_TYPES Required. Provides the tender types that will be allowed and displayed by Square Register. Must be a non-empty comma-delimited set of the following:
  • com.squareup.register.TENDER_CARD
  • com.squareup.register.TENDER_CARD_ON_FILE
  • com.squareup.register.TENDER_CASH
  • com.squareup.register.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 Register 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.register.NOTE Optional. A note to add to your transaction if completed successfully.
S.com.squareup.register.REQUEST_METADATA Optional. The state parameter that is returned in the response for the developer's use.

Processing the transaction in Square Register

When the merchant's Android device switches over to Square Register, 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 Register

After Square Register 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.register.CLIENT_TRANSACTION_ID
  • com.squareup.register.SERVER_TRANSACTION_ID (if processing a card transaction online)

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

  • com.squareup.register.ERROR_CODE
  • com.squareup.register.ERROR_DESCRIPTION

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

Error codes

If a Register API transaction fails for any reason, Square Register returns an error code as the value of the com.squareup.register.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 Register API is not currently available.
ILLEGAL_LOCATION_ID The provided location ID does not correspond to the location currently logged in to Square Register.
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 Register.
NO_NETWORK Square Register was unable to validate the Register API request because the Android device did not have an active network connection.
NO_RESULT Square Register did not return a transaction result.
TRANSACTION_ALREADY_IN_PROGRESS Another Square Register 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 Register API.
UNEXPECTED An unexpected error occurred.
UNSUPPORTED_API_VERSION The installed version of Square Register doesn't support this version of the Register 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 Register.

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?