Build on iOS
Build for iOS to process in-person payments with Square hardware with the Reader SDK.
On this page
Prerequisites and assumptions
To build with the Reader SDK, the following must be true:
You have a Square account enabled for payment processing. If you have not enabled payment processing on your account (or you are not sure), visit squareup.com/activation.
You are using Xcode 10.2 or later.
You have set your Xcode iOS deployment target to iOS 11.
Note
If you need to support iOS 10, you must restrict build architectures to arm64
using the following steps:
Open the Build Settings tab for your target in Xcode.
Set the
Architectures
andValid Architectures
values toarm64
.Open your Info.plist file in Xcode.
Set
UIRequiredDeviceCapabilities
toarm64
.
Your application is not able to run on a device that does not support 64-bit code.
Additionally, this guide makes the following assumptions:
Your version of the Reader SDK adheres to the Square update policy. To limit risk to developers and their users, Square enforces an update policy for the Reader SDK requiring developers keep their version of the Reader SDK current.
You are generally familiar with developing applications on iOS. If you are new to iOS development, you should visit the Apple Training Center before continuing.
Information you need
To use the steps in this topic, you need:
Your application ID. Find your application ID on the Credentials page of your Square application in the Developer Dashboard.
Your Reader SDK repository password. Find your Reader SDK repository password on the Reader SDK page of your Square application in the Developer Dashboard.
Step 1: Request Reader SDK credentials
Open the Square Developer Dashboard. You are prompted to sign in or create an account.
Create a Square application.
Choose the new application to open the Square application settings pages.
Open the Reader SDK page, and then choose Request Credentials to generate your Reader SDK repository password.
Step 3: Configure your iOS project for the Reader SDK
Add a Reader SDK build phase
Add the Reader SDK to your project:
Open the General tab for your application target in Xcode.
Drag the newly downloaded SquareReaderSDK.xcframework into the Embedded Binaries section, and then choose Finish in the dialog box that appears.
Open the Xcode workspace or project for your application.
On the Build Phases tab for your application target, choose the + button (at the top of the pane).
Choose New Run Script Phase.
Paste the following into the editor panel of the new run script:
Important
To avoid "No such file or directory" build errors, make sure that the Reader SDK Run Script phase is the last phase in the list.
Disable bitcode
The Reader SDK does not currently support bitcode. To disable bitcode:
Open the Build Settings tab for your application target.
In the top right search field, search for "bitcode".
Change the value of Enable Bitcode to NO.
Embed Swift libraries
If your application target is pure Objective-C and contains no Swift code, you must include the standard Swift libraries with your application.
Open the Build Settings tab for your application target.
In the top right search field, search for "embed swift".
Change the value of Always Embed Swift Standard Libraries to Yes.
Add support for required interface orientations
In Xcode, open the General tab for your application target.
Make sure the Landscape Left and Landscape Right device orientations are supported, as shown:
If your application runs on iPhone, it must support portrait and landscape interface orientations so that the Reader SDK can display the signature screen during checkout.
If you want specific screens in your application to only support the portrait orientation, you can override the supportedInterfaceOrientations
method in your UIViewController
subclasses.
Update your Info.plist
Add or update the following key-value pairs on the Info tab for your application target to explain why your application requires these device permissions. Xcode can display human-readable labels (such as Privacy - Microphone Usage Description) rather than the raw keys.
Key | Description |
---|---|
NSLocationWhenInUseUsageDescription | This application integrates with Square for card processing. To protect buyers and sellers, Square requires your location to process payments. |
NSMicrophoneUsageDescription | This application integrates with Square for card processing. To swipe magnetic cards using the headphone jack, Square requires access to the microphone. |
NSBluetoothPeripheralUsageDescription | This application integrates with Square for card processing. Square uses Bluetooth to connect your device to compatible hardware. |
NSCameraUsageDescription | This application integrates with Square for card processing. Upload your account logo, feature photo, and product images with the photos stored on your mobile device. |
NSPhotoLibraryUsageDescription | This application integrates with Square for card processing. Upload your account logo, feature photo, and product images with the photos stored on your mobile device. |
NSBluetoothAlwaysUsageDescription | This application integrates with Square for card processing. Square uses Bluetooth to connect your device to compatible hardware. |
Note
Your application does not need to request Bluetooth, Camera, or Photo Library permissions to use the Reader SDK. The usage descriptions are required due to the way the Reader SDK is built.
Step 4: Request location permission
Add code to ensure that your application has permission to use location services before starting a checkout flow. The location permission is managed by Apple's CLLocationManager class.
Step 5: Request microphone permission
Add code to ensure that your application has permission to access the microphone before starting checkout. The microphone permission is managed by Apple's AVAudioSession
class. You must have the record
permission from AVAudioSession
to use Square Magstripe Readers.
Step 7: Add code to request a mobile authorization code
The Reader SDK requires a mobile authorization code from the Mobile Authorization API. Mobile authorization codes allow custom mobile applications to process payments on Square hardware on behalf of a specific Square account for a given location.
Mobile authorization codes are short lived and should be used immediately to authorize the Reader SDK. Authorization is valid until it is explicitly revoked by calling deauthorize
or your application fails to take a payment within 90 days. Mobile authorization codes do not need to be manually refreshed under normal operations.
Did you know?
Production applications should request mobile authorization codes programmatically, but you can generate mobile authorization codes on the Reader SDK page of your application settings or manually with cURL during development.
Create a function, retrieveAuthorizationCode
, to handle the work of calling your authorization service and handling the result.
Step 9: Implement CheckoutControllerDelegate methods
Your view controller must conform to the SQRDCheckoutControllerDelegate
protocol to handle results and errors from the checkout flow. In most cases, your view controller should implement SQRDCheckoutControllerDelegate
. If you choose to implement the delegate as a separate object, make sure it is retained until the checkout flow completes.
Did you know?
This view controller is a good place to add a button that starts the contactless reader connect flow using the Reader SDK settings view controller. A Square contactless reader cannot be connected until the Reader SDK is authorized. Authorization is completed in Step 8 which means you can now connect a reader. See Connect a Contactless Reader for information about connecting a reader.
Step 11: Add code to handle the checkout result
Implement the success and failure delegate methods. For now, print the checkout result to the Xcode console on success and error information on failure.
The Reader SDK provides error types for all failable operations. For example, errors that occur while presenting the checkout flow are always of the SQRDCheckoutControllerError
type. Error objects always contain user displayable details (error codes and descriptions) and debugging information (debug codes and debug messages).
Test the Reader SDK on iOS
The Reader SDK provides a testing module that contains additional initializers that are not exposed in the Reader SDK framework. You can use these initializers to construct mock objects in your tests. For example, you might initialize a SQRDCard
object in a unit test and use it to verify the behavior of your application.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.