Point of Sale API

Mobile Web Technical Reference

Technical Reference for the Point of Sale API Mobile Web.

Mobile Web
Point of Sale API

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.

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_CASH;
    end">Start Transaction</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.

For step by step guidance on opening the Point of Sale app from your mobile web app, read the Mobile Web Setup Guide.

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_IDRequired. The ID of the customer.
S.com.squareup.pos.WEB_CALLBACK_URIRequired. The callback URI that Square Point of Sale will use to send a response.
S.com.squareup.pos.CLIENT_IDRequired. Your client ID.
S.com.squareup.pos.LOCATION_IDRequired. The location ID of the seller.
S.com.squareup.pos.API_VERSIONRequired. The targeted version of the Square Point of Sale API, e.g., 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. Timer begins when the Thank You screen loads.
If the merchant taps Add Customer or Save Card On File on the Thank You screen, auto return will be disabled. The merchant can also manually return to the calling app by tapping New Sale.
* Minimum Value: 320
* Maximum Value: 10000
S.com.squareup.pos.CURRENCY_CODERequired. The currency code, e.g., USD
i.com.squareup.pos.TOTAL_AMOUNTRequired. 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.pos.TENDER_TYPESRequired. 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:
* 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'. Identifies the package name of the application responding to this intent.
S.browser_fallback_urlOptional. 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.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 app
Permalink Get a link to this section

If successful, the Android Point of Sale app will return to your callback URL with the same parameters set in your URL. The parameters will contain information on the completed transaction.

If a Point of Sale API transaction fails for any reason, Square Point of Sale 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_{ERROR_NAME}.

Error NameDescription
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 (e.g., 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_CANCELEDTransaction 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 the Point of Sale SDK.
UNSUPPORTED_WEB_API_VERSIONThe Web API used is not supported in the supplied API version (must be >= v1.3).
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. data 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 on opening the Point of Sale app from your mobile web app, read the Mobile Web Setup Guide.

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 will send its response to.

For native apps, the protocol of this URL (for example, myapp-url-scheme in the JSON example above) must match the custom URL scheme you specified on your Application Dashboard.

For web apps, this value must match the callback URL you specified in your Application Dashboard.

client_idstringRequired. Your Application ID, available from your Application Dashboard.
optionsobjectRequired. Contains additional payment options, described in Additional payment options
versionstringRequired. The version of the Point of Sale API to use to process the transaction. This value should be 1.3, 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's included in Square Point of Sale's response to your app 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 will fail with an error.

You can fetch a merchant'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 and

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 (i.e., taxes) the merchant has created in Square Point of Sale are not automatically applied to the payment.

Default value: false

auto_returnbooleanOptional. If true, Square Point of Sale automatically switches back to your app following a short timeout after the transaction completes. Otherwise, the merchant must tap the New Salebutton in Square Point of Sale to return to your app.

If the merchant taps the Add Customer or 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 will not automatically switch back to your app, even if this option is set to true.

skip_receiptbooleanOptional.

Default value: 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 app
Permalink Get a link to this section

After Square Point of Sale finishes processing a transaction (or encounters an error), it switches back to your app via 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.
See Handling error codes for possible values and what they indicate.
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 app has one of the following values:

NameDescription
amount_invalid_formatThe request had a missing or invalid amount to charge.
amount_too_largeThe request's amount to charge was too large.
amount_too_smallThe request's amount to charge was too small.
client_not_authorized_for_userPoint of Sale versions prior to 4.53 require the developer to guide merchants through OAuth before allowing them to take payments with Point of Sale API. As of Point of Sale 4.53, this error type is deprecated. Read more about Square OAuth.
could_not_performThe request could not be performed. This is usually because there is an unfinished transaction pending in Square Point of Sale. Merchants 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 merchant 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 in the logged in Square merchant'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 merchant is not currently logged in to Square Point of Sale.
payment_canceledThe merchant canceled the payment in Square Point of Sale.
unsupported_api_versionThe installed version of Square Point of Sale doesn't 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.