Menu Apps
Manage Apps

Using the Register API for iOS

Register API setup

Before you can use the Register API in your iOS app, you need to perform the following setup tasks:

[Native app only] Specify the URL schemes that your app uses

The Register API uses URLs with custom schemes to communicate between your native app and Square Register. Square Register accepts URLs with the scheme square-commerce-v1 and sends transaction results back to your app using a URL scheme that you define.

After you decide on a URL scheme (such as myapp-url-scheme), add the CFBundleURLTypes key to your Info.plist file to indicate that your app handles URLs that use the scheme:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>Editor</string>
    <key>CFBundleURLName</key>
    <string>com.myapp.register-api-response</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp-url-scheme</string>
    </array>
  </dict>
</array>

You also need to indicate that your app uses the square-commerce-v1 URL scheme to open Square Register. Add the LSApplicationQueriesSchemes key to your Info.plist file like so:

<key>LSApplicationQueriesSchemes</key>
<array>
  <string>square-commerce-v1</string>
</array>

For more information on defining custom URL schemes and handling requests that use them, see Apple's App Programming Guide for iOS.

[Web app only] Define a callback URL for your app

For web apps, Square Register sends transaction results via an HTTP GET request to a URL you specify. Ensure that you have a publicly accessible endpoint in place to receive these results.

[All apps] Enroll your application with Square

If you haven't yet, complete all of the steps described in Square APIs: Getting started before continuing.

Next, go to your application's control panel in the application dashboard. Under the Register API tab, provide the following information about your iOS app:

  • The app's bundle ID (native apps only)
  • The app's custom URL scheme (native apps only)
  • The app's web callback URL (web apps only)

Be sure to Save your changes.

[All apps] Install the latest version of Square Register on your iOS device

Square Register is available on the App Store.

  • Register API v1.0 is supported in Square Register 4.34 and later.
  • Register API v1.1 is supported in Square Register 4.50 and later.
  • Register API v1.2 is supported in Square Register 4.53 and later.

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

Using the Square Register SDK for iOS (recommended)

If you're developing a native iOS app, you can add the Square Register SDK for iOS to your app. The Register SDK provides a helpful wrapper around the API, which simplifies the development process.

The SDK is available on Github, along with a sample application that demonstrates its use.

See the full SDK reference to learn more.

Initiating a Square Register transaction from your app

To initiate a Square Register transaction from your app, you open a URL with the following format:

square-commerce-v1://payment/create?data=PARAMETERS
  • For web apps, you can open this URL just as you would any other URL on a webpage.
  • For native iOS apps, you use the openURL: method of UIApplication.

The query parameter in the URL, data, is a percent-encoded JSON object that contains the information Square Register 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.2",
  "notes": "Rental fee",
    "options": {
    "supported_tender_types": [
      "CREDIT_CARD",
      "CASH",
      "OTHER",
      "SQUARE_GIFT_CARD",
      "CARD_ON_FILE"
    ]
  }
}

Assuming you have an unencoded string, unencodedString, you percent-encode it for use in a URL query string with the stringByAddingPercentEncodingWithAllowedCharacters: method, like so:

NSString *encodedString = [unencodedString stringByAddingPercentEncodingWithAllowedCharacters:[NSCharacterSet URLQueryAllowedCharacterSet]];

If you're developing an iOS web application, this Javascript sample demonstrates encoding a Register 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
    "version": "1.2",
    "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 Register, in the smallest unit of the corresponding currency. For US dollars, this value is in cents.

callback_url string

Required. The URL that Square Register 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 Register API to use to process the transaction. This value should be 1.2, the current version of the API.

If the installed version of Square Register does not support the specified version of the Register API, an unsupported_api_version error is returned.

merchant_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 Register, 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 Register'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 Register 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 Register 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 Register are not automatically applied to the payment.

Default value: false

auto_return boolean

Optional. If true, Square Register automatically switches back to your app following a short timeout after the transaction completes. Otherwise, the merchant must tap the New Salebutton in Square Register 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 Register will not automatically switch back to your app, even if this option is set to true.

skip_receipt boolean

Optional. If true, Square Register does not display digital receipt options for the buyer after the transaction completes.

Default value: false

Processing the transaction in Square Register

When the merchant's iOS device switches over to Square Register, the details of the transaction are prepopulated. The merchant can either process the transaction or cancel it. Either way, when the action completes, the iOS device returns to your app and provides details of the result.

Receiving data from Square Register

After Square Register finishes processing a transaction (or encounters an error), it switches back to your app via the callback_url you provided in the original request.

For native iOS apps, your app's UIApplicationDelegate needs to implement the application:openURL:options: method to handle the callback, like so:

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<NSString *,id> *)options {

  // Make sure that the URL comes from Square Register and fail if it doesn't
  if (![[options objectForKey:UIApplicationOpenURLOptionsSourceApplicationKey] hasPrefix:@"com.squareup.square"]) {
    return NO;
  }

  // Unencode the URL's query string
  NSString *queryString = [[url query] stringByRemovingPercentEncoding];

  // Extract the JSON string from the query string
  queryString = [queryString stringByReplacingOccurrencesOfString:@"data=" withString:@""];

  // Convert the JSON string to an NSData object for serialization
  NSData *queryData = [queryString dataUsingEncoding:NSUTF8StringEncoding];

  // Serialize the JSON data into a dictionary
  NSDictionary* jsonObject = [NSJSONSerialization JSONObjectWithData:queryData options:0 error:nil];

  // Query the dictionary for result details

  return YES;
}

The URL provided to this delegate method includes a single query parameter, data, which is a URL-encoded JSON object that describes the result of the operation.

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

Register versions prior to 4.53 require the developer to guide merchants through OAuth before allowing them to take payments with Register API. As of Register 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 Register. Merchants must open Square Register 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 Register 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 Register.
payment_canceled The merchant canceled the payment in Square Register.
unsupported_api_version The installed version of Square Register doesn't support the specified version of the Register API.
unsupported_currency_code The currency code provided in the request is not currently supported in the Register API.
unsupported_tender_type The request included a tender type that is not currently supported by the Register API.
user_id_mismatch The business location currently logged in to Square Register does not match the location represented by the merchant_id you provided in your request.
user_not_active The currently logged in location has not activated card processing.

Using the Register API in offline mode

Merchants can process Register API payments in Square Register'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 Register API payment from your application in the last 24 hours.

When a merchant processes a Register API payment in offline mode, Square Register'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 Register 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?