Take Payments

Point of Sale API iOS Setup

Open the Square Point of Sale app from your mobile iOS application to process in-person payments using Square hardware.

Assumptions

This guide makes the following assumptions:

The example code in this guide assumes the following:

  • You are building an iOS app. For guidance on building an Android app, check our Android Setup Guide. For guidance on building a Mobile Web app, check our Mobile Web Setup Guide.
  • Your are using the Point of Sale SDK for iOS. The Point of Sale SDK provides a helpful wrapper around the Point of Sale API, which simplifies the development process.
  • You are using Objective-C. The Point of Sale SDK supports Objective-C and Swift.
  • You using a personal access token as your authorization token. The Point of Sale API does not support sandbox at this time. Personal access tokens are appropriate for testing and development.

Step 1: Install the Square Point of Sale app

We recommend installing the latest version of the Square Point of Sale app from the App Store to use with the latest version of the [the Point of Sale SDK for iOS]https://github.com/square/SquarePointOfSaleSDK-iOS).

To check your installed version of the Point of Sale app:

  1. Open the Point of Sale app
  2. Go to Help > Support.
  3. Scroll to the bottom of the Support screen.

If you must use an older version of the Point of Sale SDK, you will need to install a compatible version of the Point of Sale app:

App Version iOS SDK Version
4.59 and later v1.3
4.53 and later v1.2
4.50 and later v1.1
4.34 and later v1.0

Step 2: Register your application

The Square Point of Sale app for iOS will only accept requests if it can authenticate the source of the request. Square uses the following to authenticate application requests:

  • App bundle ID — The Square Point of Sale app uses the bundle ID of an app to validate the source of incoming requests.
  • App URL scheme (such as myapp-url-scheme). The URL scheme you provide must match the CFBundleURLSchemes attribute of the Info.plist file for your application.

To register your application:

  1. Go to the Point of Sale API tab of your application's settings in the Application Dashboard.
  2. In the iOS section enter your app bundle IDs and url schemes.
  3. Click "Save".

Step 3: Add the Square Point of Sale SDK to your project

Install the Point of Sale SDK manually

To install the Point of Sale SDK manually, download the SquarePointOfSaleSDK-iOS repo on Github.

Add the Point of Sale SDK to a Cocoapods project

If you use Cocoapods to manage your dependencies, install the Point of Sale SDK with the following shell command:

platform :ios, '9.0'
pod 'SquarePointOfSaleSDK'

Once installed, you can use the following commands to ensure you have the most recent version of the Point of Sale SDK installed.

pod update
pod install --repo-update

Add the Point of Sale SDK to a Carthage project

If you use Carthage to manage your dependencies, install the Point of Sale SDK with the following shell command:

github "Square/SquarePointOfSaleSDK-iOS"

Step 4: Add your URL schemes

Set your URL scheme as square-commerce-v1 and set your custom response URL scheme.

  1. Add the request URL scheme as a LSApplicationQueriesSchemes key into your Info.plist file to indicate that your app uses the square-commerce-v1 URL scheme to open Square Point of Sale:
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>square-commerce-v1</string>
</array>
  1. Add your custom response URL scheme as CFBundleURLTypes keys in your Info.plist file:
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>Editor</string>
    <key>CFBundleURLName</key>
    <string>YOUR_BUNDLE_URL_NAME</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp-url-scheme</string>
    </array>
  </dict>
</array>

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

Step 5: Add code to initiate a transaction from your app

  1. Create an SCCAPIRequest object with the details of your transaction.
// Replace with your app's callback URL.
// Note: You can retrieve this value from Info.plist
NSURL *const callbackURL = [NSURL URLWithString:redirectUrl];

// 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];

Step 6: Add code to send the transaction to the Square Point of Sale app

Use the SCCAPIConnection class to send your SCCAPIRequest to the Square Point of Sale app:

BOOL success = [SCCAPIConnection performRequest:request error:&error];

Step 7: Add code to receive data from the Square Point of Sale app

You need to add code to receive results from the Square Point of Sale app and do something with it. The following sample code will implements the application:openURL:options: method in your UIApplicationDelegate to receive the results.

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<NSString *,id> *)options;
{
    NSString *const sourceApplication = options[UIApplicationOpenURLOptionsSourceApplicationKey];
    // Make sure the URL comes from Square Point of Sale; fail if it doesn't.
    if (![sourceApplication hasPrefix:@"com.squareup.square"]) {
        return NO;
    }

    // The response data is encoded in the URL and can be decoded as an SCCAPIResponse.
    NSError *decodeError = nil;
    SCCAPIResponse[] *const response = [SCCAPIResponse responseWithResponseURL:url error:&decodeError];

    if (response.isSuccessResponse) {
      //Print checkout object
      NSLog(@"Transaction successful: %@", response);

    } else if (decodeError) {
      //Print decode error
        NSLog(@"Decode Error: %@", decodeError);
    }
    else {
      //Print the error code
        NSLog(@"Request failed: %@", response.error);
    }

    return YES;
}

If the transaction was successful, this sample code will print the newly created checkout object.

If there was an error, the sample code prints the error description.

Step 8: Test your code

  1. Log into the Square Point of Sale app with the business location you want to use to accept payments.
  2. Open your app and initiate a transaction.
  3. Test your callbacks:
    1. Test the cancellation callback: Cancel the transaction
    2. Test the success callback: To receive a success callback, complete a cash transaction.

The Square sandbox does not support credit card testing for mobile. To test with credit cards in production, connect your Square Reader and process small card payments (as low as 1 USD), then issue refunds from Square Point of Sale. To test your app in development, see our recommendations for testing on mobile.

Prev
< Point of Sale API Overview
Next
iOS Technical Reference >

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