Using the Point of Sale API for iOS

Point of Sale API setup

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

Enroll your application with Square

If you haven't yet, complete the steps in Square APIs: Getting started before you begin developing with the Point of Sale API.

Next, go to your application's control panel in the Application Dashboard. Under the Point of Sale API tab, provide the following information about your iOS app:

  • The app's bundle ID
  • The app's custom URL scheme

Be sure to Save your changes.

Add the Square Point of Sale SDK for iOS to your app

The Point of Sale 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.

Specify the URL schemes that your app uses

The Point of Sale API uses URLs with custom schemes to communicate between your native app and Square Point of Sale. Square Point of Sale 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.point-of-sale-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 Point of Sale. 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.

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 app

Initiating a transaction with Square Point of Sale

Initiating a Square Point of Sale transaction with the Point of Sale SDK happens in two steps:

  1. Create an SCCAPIRequest object with the details of the transaction you want to charge.
  2. Use the SCCAPIConnection class to send your SCCAPIRequest along to Square Point of Sale to be processed.

The following Objective-C code snippet demonstrates generating an SCCAPIRequest object and sending it to Square Point of Sale (you can see a Swift example here):

// Replace with your app's callback URL.
NSURL *const callbackURL = [NSURL URLWithString:@"your-url-scheme://"];

// Specify the amount of money to charge.
SCCMoney *const amount = [SCCMoney moneyWithAmountCents:100 currencyCode:@"USD" error:NULL];

// Your client ID is the same as your Square Application ID.
// Note: You only need to set your client ID once, before creating your first request.
[SCCAPIRequest setClientID:YOUR_CLIENT_ID];

SCCAPIRequest *request = [SCCAPIRequest requestWithCallbackURL:callbackURL
                                                        amount:amount
                                                userInfoString:nil
                                                    merchantID:nil
                                                         notes:@"Coffee"
                                                    customerID:nil
                                          supportedTenderTypes:SCCAPIRequestTenderTypeAll
                                             clearsDefaultFees:NO
                               returnAutomaticallyAfterPayment:NO
                                                         error:&error];
When you're ready to charge the customer, bring Point of Sale into the foreground to complete the payment:
BOOL success = [SCCAPIConnection performRequest:request error:&error];

Handling error codes

If an error occurs during the creation of the SCCAPIRequest object, Square Point of Sale API returns an error described here.

This value is available in the error parameter passed in the creation of the SCCAPIRequest object outlined above.

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 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 Point of Sale

Square Point of Sale sends data back to your iOS app via the callbackURL you provide in your request. To receive the data, your app's UIApplicationDelegate needs to implement the application:openURL:options: method.

The following Objective-C code snippet demonstrates retrieving the SCCAPIResponse sent back to your app (you can see a Swift example here):

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)URL options:(NSDictionary<NSString *,id> *)options;
{
    NSString *const sourceApplication = options[UIApplicationOpenURLOptionsSourceApplicationKey];
    if ([sourceApplication hasPrefix:@"com.squareup.square"]) {
        SCCAPIResponse *const response = [SCCAPIResponse responseWithResponseURL:URL error:&decodeError];
        ...
        return YES;
    }
    return NO;
}

Handling error codes

If an error occurs during a Point of Sale API transaction, Square Point of Sale returns one of the error codes described here.

This value is available in the error_code field of the SCCAPIResponse object passed back in the UIApplicationDelegate method outlined above.

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.

Ask for help on Stack Overflow or join our Slack channel