Applies to: Point of Sale API - iOS | Point of Sale API - Android
Review the technical reference for the Point of Sale API Mobile Web.
For Japanese sellers, e-money payments are supported with these Mobile Web SDK URL parameters:
- Android -
TENDER_TYPES.TENDER_CARD. - iOS -
supported_tender_types.CREDIT_CARD.
To initiate a transaction from your website, you supply a specially crafted link or button similar to the following to direct the user to the Square Point of Sale application.
The following example starts a $1 USD 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_CASH;
end">Start Transaction</a>Notice that a list of key-value pairs is delimited with a semicolon and wrapped by special Android start and end tokens (intent:#Intent; and end) and is embedded in the target URL.
For step-by-step guidance opening the Point of Sale application from your mobile web application, see Build on Mobile Web.
| Name | Description |
|---|---|
| action | Required - This must be com.squareup.pos.action.CHARGE. This represents a Square transaction request. |
S.com.squareup.pos.CUSTOMER_ID | Optional - The ID of the customer. |
S.com.squareup.pos.WEB_CALLBACK_URI | Required - The URL that the Square Point of Sale application sends its response to. For native applications, the protocol of this URL (for example, myapp-url-scheme in the previous JSON example) must match the custom URL scheme you specified in the Developer Dashboard. For web applications, this value must match the callback URL you specified in the Developer Dashboard. |
S.com.squareup.pos.CLIENT_ID | Required - Your client ID. |
S.com.squareup.pos.LOCATION_ID | Optional - The location ID of the seller. |
S.com.squareup.pos.API_VERSION | Required - The targeted version of the Square Point of Sale API (such as V2.0). |
l.com.squareup.pos.AUTO_RETURN_TIMEOUT_MS | Optional - The number of milliseconds that the Square Point of Sale application should wait for the Thank You screen before automatically returning to the calling application. The timer begins when the Thank You screen loads. If the seller chooses Add Customer or Save Card On File on the Thank You screen, automatic return is disabled. The seller can also manually return to the calling application by choosing New Sale. – The minimum value is 3200. – The maximum value is 10000. |
S.com.squareup.pos.CURRENCY_CODE | Required - The currency code (such as USD). |
i.com.squareup.pos.TOTAL_AMOUNT | Required - The total amount represented in the smallest unit of the supplied currency (for example, a value of 100 corresponds to $1.00 USD). |
S.com.squareup.pos.TENDER_TYPES | Required - Provides the tender types that are allowed and displayed by the Square Point of Sale application, which 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– com.squareup.pos.TENDER_PAYPAY |
| package | Recommended - If set, this must be 'com.squareup', which identifies the package name of the application responding to this intent. |
S.browser_fallback_url | Optional - If the Point of Sale application isn't installed, Android routes to this supplied URL. If missing, Android routes to the Play Store if the 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's returned in the response for the developer's use. |
If successful, the Android Point of Sale application returns to your callback URL with the same parameters set in your URL. The parameters contains information about the completed transaction.
Android results are returned as query parameter values with the form com.squareup.pos.{RESULT_NAME}.
| Name | Type | Description |
|---|---|---|
SERVER_TRANSACTION_ID | string | The unique ID of the processed transaction, if it succeeds. You can use this ID to get the full details of the payment with the RetrieveTransaction endpoint. This parameter is absent if an error occurs or if the transaction was processed in Offline Mode. |
CLIENT_TRANSACTION_ID | string | The transaction's device-specified ID, generated in case the payment needed to be processed in Offline Mode. Note that this value is present even if the payment isn't processed in Offline Mode. This parameter is absent if an error occurs. |
REQUEST_METADATA | string | The state parameter that's returned in the response for the developer's use. |
ERROR_CODE | string | A code, such as TRANSACTION_CANCELED, that indicates the type of error that occurs, if any. See Android error codes for possible values and what they indicate. |
ERROR_DESCRIPTION | string | The description of the error. |
If a Point of Sale API transaction fails for any reason, the Square Point of Sale application returns an error code as the value of the com.squareup.pos.ERROR_CODE query parameter in the response.
Android error codes are returned as query parameter values with the form com.squareup.pos.{ERROR_CODE}.
| Error code | Description |
|---|---|
CUSTOMER_MANAGEMENT_NOT_SUPPORTED | The Square account used doesn't support customer management. |
DISABLED | The Point of Sale API isn't currently available. |
ILLEGAL_LOCATION_ID | The provided location ID doesn't 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 (such as, 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 didn't have an active network connection. |
NO_RESULT | Square Point of Sale didn't return a transaction result. |
TRANSACTION_ALREADY_IN_PROGRESS | Another Square Point of Sale transaction is already in progress. |
TRANSACTION_CANCELED | The transaction was canceled in Square Point of Sale. |
UNAUTHORIZED_CLIENT_ID | The application with the provided client ID isn't authorized to use the Point of Sale API. |
UNEXPECTED | An unexpected error occurs. |
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 | The Web API used isn't supported in the supplied API version, which must be version 1.3 or later. |
USER_NOT_ACTIVATED | Square Point of Sale tried to process a credit card transaction, but the associated Square account isn't activated for card processing. |
USER_NOT_LOGGED_IN | No user is currently logged in to Square Point of Sale. |
To initiate a Square Point of Sale transaction from your website, you open a URL with a single query parameter called data. The data parameter is a percent-encoded JSON object that contains the information that Square Point of Sale needs to process the transaction request.
square-commerce-v1://payment/create?data={REPLACE ME}
For step-by step-guidance opening the Point of Sale application from your mobile web application, see Build on Mobile Web.
| Name | Type | Description |
|---|---|---|
amount_money | Money | Required - The amount of money to charge with Square Point of Sale, in the smallest unit of the corresponding currency. For US dollars, this value is in cents. |
callback_url | string | Required - The URL that Square Point of Sale sends its response to. For native applications, the protocol of this URL (for example, myapp-url-scheme in the previous JSON example) must match the custom URL scheme you specified in the Developer Dashboard. For web applications, this value must match the callback URL you specified in the Developer Dashboard. |
client_id | string | Required - Your application ID, which is available in the Developer Dashboard. |
options | object | Required - Contains additional payment options, described in Specifying additional payment options. |
version | string | Required - The version of the Point of Sale API to use to process the transaction. This value should be 1.3, which is the current version of the API. If the installed version of Square Point of Sale doesn't support the specified version of the Point of Sale API, an unsupported_api_version error is returned. |
location_id | string | Optional - Provide the ID of one of the business locations in this parameter to require that the transaction be processed by that location. If the specified location isn't currently signed in to Square Point of Sale, the transaction fails with an error. You can get your location ID using the ListLocations endpoint. |
state | string | Optional - If you provide this value, it's included in the Square Point of Sale response to your application after the payment completes. Use this parameter to associate any helpful state information with the payment request. |
notes | string | Optional - A custom note to associate with the resulting payment. This note is included in the itemizations field of Payment objects returned by the ListPayments and RetrievePayment endpoints. |
customer_id | string | Optional - Provide the ID of one of the business customers in this parameter to require that the transaction be linked with that customer. If the Square account doesn't support customer management or an invalid customer ID is specified, the transaction fails with an error. An Internet connection is also required for Square Point of Sale to retrieve the customer's details for the specified customer ID. If there is no Internet connection, the transaction fails with an error. You can fetch a seller's customer IDs using the ListCustomers or SearchCustomers endpoint. |
You can specify additional payment options by adding the option field to your data object.
| Name | Type | Description |
|---|---|---|
supported_tender_types | string[] | Required - The types of tender that Square Point of Sale is allowed to accept for the payment. The following tender types are supported: – CREDIT_CARD– CASH– OTHER– SQUARE_GIFT_CARD– CARD_ON_FILE– PAYPAY |
clear_default_fees | boolean | Optional - If true, default fees (such as taxes) that the seller has created in Square Point of Sale aren't automatically applied to the payment.The default value is false. |
auto_return | boolean | Optional - If true, Square Point of Sale automatically switches back to your application following a short timeout after the transaction completes. Otherwise, the seller must choose the New Sale button in Square Point of Sale to return to your application. If the seller chooses the Add Customer button or the Save Card On File button after the transaction completes to add or modify information about the customer associated with the transaction or to save the customer's card on file, then Square Point of Sale doesn't automatically switch back to your application, even if this option is set to true. |
skip_receipt | boolean | Optional - The default value is false. Set skip_receipt to false to show the digital receipt options screen after the transaction completes. To prevent the options screen from showing, set skip_receipt to true. |
After the Square Point of Sale application finishes processing a transaction (or encounters an error), it switches back to your application using the callback_url you provided in the original request.
Depending on the result of the transaction, the data object includes some or all of the following fields:
| Name | Type | Description |
|---|---|---|
transaction_id | string | The unique ID of the processed transaction, if it succeeds. You can use this ID to get the complete details of the payment with the RetrieveTransaction endpoint. This parameter is absent if an error occurs or if the transaction was processed in Offline Mode. |
client_transaction_id | string | The transaction's device-specified ID, generated in case the payment needs to be processed in Offline Mode. Note that this value is present even if the payment isn't processed in Offline Mode. This parameter is absent if an error occurs. |
status | string | This value is either ok if the payment succeeds or error if an error occurs. |
error_code | string | A code, such as payment_canceled, that indicates the type of error that occurs, if any. For possible values and what they indicate, see iOS error codes. |
state | string | This value is the same value you specified for state in your original request, if any. |
If an error occurs during a Point of Sale API transaction, the error_code field of the JSON object returned to your application has one of the following values:
| Name | Description |
|---|---|
amount_invalid_format | The request has a missing or invalid amount to charge. |
amount_too_large | The request amount to charge is too large. |
amount_too_small | The request amount to charge is too small. |
client_not_authorized_for_user | Point of Sale versions prior to 4.53 require the developer to guide sellers through OAuth before allowing them to take payments with the Point of Sale API. As of Square Point of Sale 4.53, this error type is deprecated. For more information, see OAuth API. |
could_not_perform | The request couldn't be performed. This is usually because there is an unfinished transaction pending in Square Point of Sale. The seller must open Square Point of Sale and complete the transaction before initiating a new request. |
currency_code_mismatch | The currency code provided in the request doesn't match the currency associated with the current business. |
currency_code_missing | The currency code provided in the request is missing or invalid. |
customer_management_not_supported | This seller account doesn't support customer management and therefore cannot associate transactions with customers. |
data_invalid | The URL sent to Square Point of Sale has missing or invalid information. |
invalid_customer_id | The customer ID provided in the request doesn't correspond to a customer signed in to the seller's Customer Directory. |
invalid_tender_type | The request included an invalid tender type. |
no_network_connection | The transaction failed because the device has no network connection. |
not_logged_in | A seller isn't currently logged in to Square Point of Sale. |
payment_canceled | The seller canceled the payment in Square Point of Sale. |
unsupported_api_version | The installed version of Square Point of Sale doesn't support the specified version of the Point of Sale API. |
unsupported_currency_code | The currency code provided in the request isn't currently supported by the Point of Sale API. |
unsupported_tender_type | The request included a tender type that isn't currently supported by the Point of Sale API. |
user_id_mismatch | The business location currently signed in to Square Point of Sale doesn't match the location represented by the location_id you provided in your request. |
user_not_active | The currently signed-in location hasn't activated card processing. |