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,
end, is embedded in the target URL.
|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|
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:
|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.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.pos.RESULT_REQUEST_METADATA, if supplied by the developer.
If a Point of Sale API transaction fails for any reason, Square Point of Sale 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 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.|
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.