Menu Apps

Using the Web API for iOS

Web API Setup

Before you can begin initiating Square Point of Sale transactions from your website, you need to complete the following setup steps:

Enroll your application with Square

If you haven't yet, complete steps 1 & 2 in Square APIs: Getting Started before you begin developing with the Web API.

Register your web callback URI

In order for Square Point of Sale to accept a request from your website, Square needs to verify that you have registered a web callback URI for the application in the Square developer portal.

First, go to the application dashboard, then click on the Point of Sale API tab of your application's settings. Under the Web section, specify your app's web callback URI under the corresponding field.

Be sure to save your changes.

Install the latest version of Square Point of Sale on your iOS device

Square Point of Sale is available on the App Store.

  • Point of Sale API v1.0 is supported in Square Point of Sale 4.34 and later.
  • Point of Sale API v1.1 is supported in Square Point of Sale 4.50 and later.
  • Point of Sale API v1.2 is supported in Square Point of Sale 4.53 and later.
  • Point of Sale API v1.3 is supported in Square Point of Sale 4.59 and later.

To check your installed version of Point of Sale, go to Help > Support within the app and scroll to the bottom of the Support screen.

Initiating a Square Point of Sale transaction from your website

To initiate a Square Point of Sale transaction from your website, you open a URL with the following format:

square-commerce-v1://payment/create?data=PARAMETERS

The query parameter in the URL, data, is a percent-encoded JSON object that contains the information Square Point of Sale needs to process the transaction request.

For example, a valid unencoded JSON object looks like this (replace MY_APPLICATION_ID with your application's ID):

{
  "amount_money": {
    "amount": 500,
    "currency_code": "USD"
  },
  "callback_url": "myapp-url-scheme://payment-complete",
  "client_id": "MY_APPLICATION_ID",
  "version": "1.3",
  "notes": "Rental fee",
    "options": {
    "supported_tender_types": [
      "CREDIT_CARD",
      "CASH",
      "OTHER",
      "SQUARE_GIFT_CARD",
      "CARD_ON_FILE"
    ]
  }
}

This Javascript sample demonstrates encoding a Point of Sale API URL and directing the merchant's browser to open it:

<script>
  var dataParameter = {
    "amount_money": {
      "amount" : "500",
      "currency_code" : "USD"
    },
    "callback_url" : "https://www.example.com", // Replace this value with your application's callback URL
    "client_id" : "MY_APPLICATION_ID" // Replace this value with your application's ID
    "version": "1.3",
    "notes": "notes for the transaction",
    "options" : {
      "supported_tender_types" : ["CREDIT_CARD","CASH","OTHER","SQUARE_GIFT_CARD","CARD_ON_FILE"]
    }
  };
  window.location = "square-commerce-v1://payment/create?data=" + encodeURIComponent(JSON.stringify(dataParameter));
</script>

JSON field descriptions

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

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

This code sample demonstrates a learn how to fetch a business' location IDs with 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.

The List Customers API Endpoint can be used to fetch a merchant's customers' IDs.

Additional payment options

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

Processing the transaction in Square Point of Sale

When the merchant's iOS device switches over to Square Point of Sale, the details of the transaction are pre-populated. The merchant can either process the transaction or cancel it. Either way, when the action completes, the iOS device returns to your website and provides details of the result.

Receiving data from Square Point of Sale

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.

You can parse the query parameters of the URI to determine whether the associated transaction succeeded or failed along with its accompanying metadata.

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 succeeded. You can use this ID to get the full details of the payment with the RetrieveTransaction endpoint of the Square Connect API.

This parameter is absent if the transaction was processed in offline mode, or if an error occurred.

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 was not processed in offline mode.

This parameter is absent if an error occurred.

status string

This value is either ok if the payment succeeded, or error if an error occurred.

error_code string

A code, such as payment_canceled, that indicates the type of error that occurred, 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.

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

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.

Using the Point of Sale API in offline mode

Merchants can process Point of Sale API payments in Square Point of Sale's offline mode without an internet connection. In order to do so:

  • The merchant must have enabled offline mode for their business.
  • The merchant must have processed at least one online Point of Sale API payment from your application in the last 24 hours.

When a merchant processes a Point of Sale API payment in offline mode, Square Point of Sale's response to your application does not include a transaction_id field, because Square's backend systems haven't received the transaction yet. The response does, however, include a client_transaction_id field. After the merchant's internet connection is restored and the transaction reaches Square, you can use the client_transaction_id to get the transaction's full details with the Connect API.

Transaction objects returned by the Connect API's ListTransactions endpoint include a client_id field. This field matches the value of client_transaction_id returned by the Point of Sale API. You can match against this value to fetch the full details of a transaction originally processed in offline mode. Note that it is not currently possible to filter the ListTransactions endpoint's results by the client_id field.

Additional resources

If you get stuck, check if there's a solution to your issue on Stack Overflow. Questions related to Square APIs are tagged with the square-connect label. If you can't find an answer, feel free to post a new question. Square's API development team monitors this label.

If a Square API returns an error message that is not helpful in diagnosing your issue, please contact support with the details of your issue and the error message you received.

Was this page helpful?