Point of Sale API

Mobile Web Technical Reference

Technical reference for the Point of Sale API Mobile Web.

Mobile Web on Android
Permalink Get a link to this section

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 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 semicolons and wrapped by special Android start and end tokens, intent:#Intent; and end, is embedded in the target URL.

For step-by-step guidance opening the Point of Sale application from your mobile web application, see Buid on Mobile Web.

Android URL parameters
Permalink Get a link to this section

NameDescription
actionRequired. This must be com.squareup.pos.action.CHARGE. This represents a Square transaction request.
S.com.squareup.pos.CUSTOMER_IDOptional. The ID of the customer.
S.com.squareup.pos.WEB_CALLBACK_URIRequired. 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_IDRequired. Your client ID.
S.com.squareup.pos.LOCATION_IDOptional. The location ID of the seller.
S.com.squareup.pos.API_VERSIONRequired. The targeted version of the Square Point of Sale API (such as, v2.0).
l.com.squareup.pos.AUTO_RETURN_TIMEOUT_MSOptional. The number of milliseconds that the Square Point of Sale application should wait on 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_CODERequired. The currency code (such as, USD).
i.com.squareup.pos.TOTAL_AMOUNTRequired. 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_TYPESRequired. Provides the tender types that is 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
packageRecommended. If set, this must be 'com.squareup', which identifies the package name of the application responding to this intent.
S.browser_fallback_urlOptional. If the Point of Sale application is not 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.NOTEOptional. A note to add to your transaction if completed successfully.
S.com.squareup.pos.REQUEST_METADATAOptional. The state parameter that is returned in the response for the developer's use.

Receiving a response from the Android Point of Sale application
Permalink Get a link to this section

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}.

NameTypeDescription
SERVER_TRANSACTION_IDstringThe 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_IDstringThe 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 is not processed in Offline Mode.

This parameter is absent if an error occurs.

REQUEST_METADATAstringThe state parameter that is returned in the response for the developer's use.
ERROR_CODEstringA 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_DESCRIPTIONstringThe 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
Permalink Get a link to this section

Android error codes are returned as query parameter values with the form com.squareup.pos.{ERROR_CODE}.

Error codeDescription
CUSTOMER_MANAGEMENT_NOT_SUPPORTEDThe Square account used does not support customer management.
DISABLEDThe Point of Sale API is not currently available.
ILLEGAL_LOCATION_IDThe provided location ID does not correspond to the location currently logged in to Square Point of Sale.
INVALID_CUSTOMER_IDThe provided customer ID is invalid.
INVALID_REQUESTThe information provided in this transaction request is invalid (such as, a required field is missing or malformed).
NO_EMPLOYEE_LOGGED_INEmployee management is enabled but no employee is logged in to Square Point of Sale.
NO_NETWORKSquare 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_RESULTSquare Point of Sale did not return a transaction result.
TRANSACTION_ALREADY_IN_PROGRESSAnother Square Point of Sale transaction is already in progress.
TRANSACTION_CANCELEDThe transaction was canceled in Square Point of Sale.
UNAUTHORIZED_CLIENT_IDThe application with the provided client ID is not authorized to use the Point of Sale API.
UNEXPECTEDAn unexpected error occurs.
UNSUPPORTED_API_VERSIONThe installed version of Square Point of Sale does not support this version of Point of Sale SDK.
UNSUPPORTED_WEB_API_VERSIONThe Web API used is not supported in the supplied API version, which must be version 1.3 or later.
USER_NOT_ACTIVATEDThe Square Point of Sale tried to process a credit card transaction, but the associated Square account is not activated for card processing.
USER_NOT_LOGGED_INNo user is currently logged in to Square Point of Sale.

Mobile Web on iOS
Permalink Get a link to this section

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 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.

iOS data fields
Permalink Get a link to this section

NameTypeDescription
amount_money MoneyRequired. 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_urlstringRequired. 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_idstringRequired. Your application ID, which is available in the Developer Dashboard.
optionsobjectRequired. Contains additional payment options, described in Specifying additional payment options.
versionstringRequired. 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 does not support the specified version of the Point of Sale API, an unsupported_api_version error is returned.

location_idstringOptional. Provide the ID of one of a business' locations in this parameter to require that the transaction be processed by that location. If the specified location is not currently signed in to Square Point of Sale, the transaction fails with an error.
You can get your location ID using the ListLocations endpoint.
statestringOptional. If you provide this value, it is 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.
notesstringOptional. A custom note to associate with the resulting payment.

This note is included in the itemizations field of Payment objects returned by the List Payments and Retrieve Payment endpoints.

customer_idstringOptional. Provide the ID of one of a business' customers in this parameter to require that the transaction be linked with that customer. If the Square account does not 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 ListLocations endpoint.

Specifying additional payment options
Permalink Get a link to this section

You can specify additional payment options by adding the option field to your data object.

NameTypeDescription
supported_tender_typesstring[]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
clear_default_feesbooleanOptional. If true, default fees (such as, taxes) that the seller has created in Square Point of Sale are not automatically applied to the payment.

The default value is false.

auto_returnbooleanOptional. 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 does not automatically switch back to your application, even if this option is set to true.

skip_receiptbooleanOptional.

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.

Receiving a response from the iOS Point of Sale application
Permalink Get a link to this section

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:

NameTypeDescription
transaction_idstringThe 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_idstringThe 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 is not processed in Offline Mode.

This parameter is absent if an error occurs.

statusstringThis value is either ok if the payment succeeds or error if an error occurs.
error_codestringA 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.
statestringThis value is the same value you specified for state in your original request, if any.

iOS error codes
Permalink Get a link to this section

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:

NameDescription
amount_invalid_formatThe request has a missing or invalid amount to charge.
amount_too_largeThe request amount to charge was too large.
amount_too_smallThe request amount to charge was too small.
client_not_authorized_for_userPoint 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 How OAuth Works.
could_not_performThe request could not 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_mismatchThe currency code provided in the request does not match the currency associated with the current business.
currency_code_missingThe currency code provided in the request is missing or invalid.
customer_management_not_supportedThis seller account does not support customer management and therefore cannot associate transactions with customers.
data_invalidThe URL sent to Square Point of Sale had missing or invalid information.
invalid_customer_idThe customer ID provided in the request does not correspond to a customer signed in to the seller's Customer Directory.
invalid_tender_typeThe request included an invalid tender type.
no_network_connectionThe transaction failed because the device has no network connection.
not_logged_inA seller is not currently logged in to Square Point of Sale.
payment_canceledThe seller canceled the payment in Square Point of Sale.
unsupported_api_versionThe installed version of Square Point of Sale does not support the specified version of the Point of Sale API.
unsupported_currency_codeThe currency code provided in the request is not currently supported in the Point of Sale API.
unsupported_tender_typeThe request included a tender type that is not currently supported by the Point of Sale API.
user_id_mismatchThe business location currently logged in to Square Point of Sale does not match the location represented by the location_id you provided in your request.
user_not_activeThe currently logged in location has not activated card processing.