Take Payments

Mobile Web Technical Reference

Technical Reference for the Point of Sale API Mobile Web.

This page is a technical reference for integrating a mobile web app with the Point of Sale API.

Android Mobile Web Technical Reference

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

Name Description
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
S.com.squareup.pos.TENDER_TYPES Required. 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
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.

Receiving a response from the Android Point of Sale app

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

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

IOS Mobile Web Technical Reference

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

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 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_id string Required. Your Application ID, available from your Application Dashboard.
options object Required. Contains additional payment options, described in

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, 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_versionerror is returned.

location_id string

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

state string Optional. 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.
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 List Payments and Retrieve Payment endpoints.

customer_id string Optional. 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

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

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
clear_default_fees boolean Optional. 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_return boolean Optional. 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_receipt boolean Optional. If true, Square Point of Sale does not display digital receipt options for the buyer after the transaction completes.

Default value: false

Receiving a response from the iOS Point of Sale app

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:

Name Type Description
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 is not processed in offline mode.

This parameter is absent if an error occurs.

status string This value is either ok if the payment succeeds, or errorif an error occurs.
error_code string A 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.

state string This value is the same value you specified for state in your original request, if any.

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 app has one of the following values:

Name Description
amount_invalid_format The request had a missing or invalid amount to charge.
amount_too_large The request's amount to charge was too large.
amount_too_small The request's amount to charge was too small.
client_not_authorized_for_user Point 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_perform The 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_mismatch The currency code provided in the request does not 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 merchant account does not support customer management and therefore cannot associate transactions with customers.
data_invalid The URL sent to Square Point of Sale had missing or invalid information.
invalid_customer_id The customer ID provided in the request does not correspond to a customer in the logged in Square merchant'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 merchant is not currently logged in to Square Point of Sale.
payment_canceled The merchant 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 is not currently supported in the Point of Sale API.
unsupported_tender_type The request included a tender type that is not currently supported by the Point of Sale API.
user_id_mismatch The 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_active The currently logged in location has not activated card processing.
Prev
< Point of Sale API Overview
Next
Find your Android Fingerprint >

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow