Take payments in a custom iOS application by calling the Square Point of Sale application.
Docs Home
Dev Essentials
Payments Commerce Customers Staff Merchants
Partnerships
Release notes

Docs

Docs Home
Dev Essentials
Payments
Commerce
Customers
Staff
Merchants
Partnerships
Release notes
Docs
Point of Sale API

Build on iOS

Objective C (iOS)

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

Link to section
Assumptions

The example code in this topic assumes the following:

  • You are using the Point of Sale SDK for iOS. The Point of Sale SDK for iOS provides a helpful wrapper around the Point of Sale API, which simplifies the development process.

  • You are using a personal access token as your authorization token. The Point of Sale API does not support the Square Sandbox at this time. Personal access tokens are appropriate for testing and development.

Link to section
Information you need

To use the steps in this topic, you need:

Link to section
Step 1: Install the Square Point of Sale application

You should install the latest version of the Square Point of Sale application from the Apple App Store to use with the latest version of the Point of Sale SDK for iOS.

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

  1. Open the Point of Sale application.

  2. Choose Help, and then choose Support.

  3. Scroll to the bottom of the Support screen.

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

Point of Sale versioniOS SDK versioniOS version
4.59 and laterv1.314
4.53 and laterv1.214
4.50 and laterv1.114
4.34 and laterv1.014

Link to section
Step 2: Register your application

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

  • Application bundle ID. The Square Point of Sale application uses the bundle ID of an application to validate the source of incoming requests.

  • Application 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. Open the Developer Dashboard.

  2. In the pane, choose Point of Sale API.

  3. In the iOS section, enter your application bundle IDs and URL schemes.

  4. Choose Save.

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

Link to section
Install the Point of Sale SDK manually

To install the Point of Sale SDK manually, download the SquarePointOfSaleSDK-iOS repo in GitHub.

Link to section
Add the Point of Sale SDK to a Cocoapods project

If you use Cocoapods to manage your dependencies, install the Point of Sale SDK by adding the following to your podfile:

  • 1
  • 2
platform :ios, '9.0'
pod 'SquarePointOfSaleSDK'

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

  • 1
  • 2
pod update
pod install --repo-update

Link to section
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:

  • 1
github "Square/SquarePointOfSaleSDK-iOS"

Link to section
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 application uses the square-commerce-v1 URL scheme to open Square Point of Sale.

    • 1
    • 2
    • 3
    • 4
    <key>LSApplicationQueriesSchemes</key>
<array>
    <string>square-commerce-v1</string>
</array>

  2. Add your custom response URL scheme as CFBundleURLTypes keys in your Info.plist file.

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    <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 about defining custom URL schemes and handling requests that use them, see Apple's App Programming Guide for iOS.

Link to section
Step 5: Add code to initiate a payment from your application

Create an SCCAPIRequest object with the details of your payment.

Did you know?

Information in the notes field is saved in the Seller Dashboard and printed on receipts.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
// 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];

// Note: You only need to set your application ID once, before creating your first request.
[SCCAPIRequest setApplicationID:YOUR_APPLICATION_ID];

SCCAPIRequest *request = [SCCAPIRequest requestWithCallbackURL:callbackURL
                                                        amount:amount
                                                userInfoString:nil
                                                    merchantID:nil
                                                         notes:@"Coffee"
                                                    customerID:nil
                                          supportedTenderTypes:SCCAPIRequestTenderTypeAll
                                             clearsDefaultFees:NO
                               returnAutomaticallyAfterPayment:NO
                                                         error:&error];

Link to section
Step 6: Add code to send the transaction to the Square Point of Sale application

Use the SCCAPIConnection class to send your SCCAPIRequest to the Square Point of Sale application.

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

Link to section
Step 7: Add code to receive data from the Square Point of Sale application

You need to add code to receive results from the Square Point of Sale application and do something with it.

The following sample code implements the application:openURL:options: method in your UIApplicationDelegate to receive the results. If the transaction succeeds, the sample code prints the newly created checkout object; otherwise, it prints the error description.

Important

Your application should keep track of whether a Point of Sale API request has been issued and whether a callback has been received. Because of the constraints of application-switching APIs, sellers can leave Square Point of Sale during an API request and return to your application. It is your responsibility to direct them to return to Square and finish the transaction.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
- (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 (![SCCAPIResponse isSquareResponse:url]) {
    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;
}

Link to section
Step 8: Test your code

  1. Sign in to the Square Point of Sale application with the business location that you want to use to accept payments.

  2. Open your application and initiate a transaction.

  3. Test your callbacks:

    • Test the cancellation callback by canceling a transaction.

    • Test the success callback by completing a cash transaction.

The Sandbox does not support credit card testing for mobile. To test with credit cards in production, connect your Square Reader, process small card payments (as low as $1 USD), and then issue refunds from Square Point of Sale. To test your application in development, see Testing for supported countries.

Link to section
Next step

Now that you have a basic build in place, expand on it by integrating with the Square Payments API and Refunds API.

On this page
We've made improvements to our docs.
Prefer the old format?