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,
end, is embedded in the target URL.
|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|
Provides the tender types that will be allowed and displayed by Square Register.
Must be a non-empty comma-delimited set of the following:
|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.SERVER_TRANSACTION_ID (if processing a card transaction online)
If the transaction failed, the response will have the following parameters:
In both success and error cases, the response will also include com.squareup.register.RESULT_REQUEST_METADATA, if supplied by the developer.
If a Register API transaction fails for any reason, Square Register returns
an error code as the value of the
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.|
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.