Mobile Web Technical Reference

Applies to: Point of Sale API - iOS | Point of Sale API - Android

Review the technical reference for the Point of Sale API Mobile Web.

Link to section

Overview

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.
Link to section

Mobile Web on Android

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.

Link to section

Android URL parameters

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 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_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 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
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 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.NOTEOptional - A note to add to your transaction if completed successfully.
S.com.squareup.pos.REQUEST_METADATAOptional - The state parameter that's returned in the response for the developer's use.
Link to section

Receiving a response from the Android Point of Sale application

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 isn't processed in Offline Mode.
This parameter is absent if an error occurs.
REQUEST_METADATAstringThe state parameter that's 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.

Link to section

Android error codes

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 doesn't support customer management.
DISABLEDThe Point of Sale API isn't currently available.
ILLEGAL_LOCATION_IDThe provided location ID doesn't 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 didn't have an active network connection.
NO_RESULTSquare Point of Sale didn't 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 isn't authorized to use the Point of Sale API.
UNEXPECTEDAn unexpected error occurs.
UNSUPPORTED_API_VERSIONThe installed version of Square Point of Sale doesn't support this version of the Point of Sale SDK.
UNSUPPORTED_WEB_API_VERSIONThe Web API used isn't supported in the supplied API version, which must be version 1.3 or later.
USER_NOT_ACTIVATEDSquare Point of Sale tried to process a credit card transaction, but the associated Square account isn't activated for card processing.
USER_NOT_LOGGED_INNo user is currently logged in to Square Point of Sale.
Link to section

Mobile Web on iOS

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.

Link to section

iOS data fields

NameTypeDescription
amount_moneyMoneyRequired - 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 doesn't 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 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.
statestringOptional - 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.
notesstringOptional - 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_idstringOptional - 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.
Link to section

Specifying additional payment options

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
– PAYPAY
clear_default_feesbooleanOptional - 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_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 doesn't 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.
Link to section

Receiving a response from the iOS Point of Sale application

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 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_idstringThe 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.
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.
Link to section

iOS error codes

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 is too large.
amount_too_smallThe request amount to charge is 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 OAuth API.
could_not_performThe 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_mismatchThe currency code provided in the request doesn't 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 doesn't support customer management and therefore cannot associate transactions with customers.
data_invalidThe URL sent to Square Point of Sale has missing or invalid information.
invalid_customer_idThe customer ID provided in the request doesn't 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 isn't 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 doesn't support the specified version of the Point of Sale API.
unsupported_currency_codeThe currency code provided in the request isn't currently supported by the Point of Sale API.
unsupported_tender_typeThe request included a tender type that isn't currently supported by the Point of Sale API.
user_id_mismatchThe 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_activeThe currently signed-in location hasn't activated card processing.