Pair and Manage Card Readers

Link to section

Overview

The Mobile Payments SDK's ReaderManager lets you pair and monitor changes in Square readers.

Link to section

Requirements and limitations

  • To successfully pair a contactless reader and take payments, your application must request location and Bluetooth permissions from the user.
  • Physical reader devices cannot be used in the Square Sandbox. For testing purposes, you can use the Mock Reader UI to pair simulated readers and process mock payments with your application in the Square Sandbox.
Link to section

Settings Manager

The Mobile Payments SDK offers a pre-made reader settings screen you can use in your application by calling MobilePaymentsSDK.shared.settingsManager.presentSettings(viewController: self) { _ in }. This screen includes two tabs. The Devices tab displays the model and connection status for readers paired to the seller's phone or tablet and includes a button for pairing a new reader. The About tab displays information about the Mobile Payments SDK, authorized location, and environment used to take payments. Use the settingsManager.sdkSettings to programmatically retrieve information about the current environment (either production or sandbox) and the current version.

With the SettingsManager, you can also view PaymentSettings for the Square seller authenticated to your application, such as whether they have the ability to take payments offline.

A graphic showing the Square-provided settings screen for the Mobile Payments SDK. The "Devices" and "About" tabs are shown

Link to section

Reader Manager

If you want more control over your reader pairing and management screens, you can create your own using information from the Mobile Payments SDK's ReaderManager. This manager provides methods for pairing and forgetting readers, accessing information about a particular reader, and listening for reader status updates.

Link to section

Pairing a reader

Square Readers for magstripe are automatically detected by the Mobile Payments SDK as they are inserted or removed from a device's connection port and don't need to be paired. Likewise, the Square Stand includes a built-in reader device and doesn't need an external reader paired to take payments. Square readers for contactless and chip must be paired with the Mobile Payments SDK using the ReaderManager.

To start searching for nearby Bluetooth readers, call readerManager.startPairing(with:), passing in a ReaderPairingDelegate, which is notified when reader pairing begins and whether the pairing succeeded or failed.

During pairing, a PairingHandle is returned and can be used to stop the pairing in progress. You should call PairingHandle.stop() any time a user leaves the screen from which they're attempting to pair a reader.

When pairing is successful, the paired reader is added to the array of available readers accessed with readerManager.readers. If the pairing fails, the delegate's readerPairingDidFail method returns an error you can use to troubleshoot and attempt pairing again. Only one reader pairing can be in progress at one time, so before calling startPairing, check the Boolean value readerManager.isPairingInProgress and only begin pairing if it's false.

Link to section

Reader information

The ReaderInfo class provides information about Square readers and stands paired with your application. These properties include:

  • The battery level and charging status.
  • The model (contactlessAndChip, magstripe, or stand).
  • The serial number.
  • The firmware version.
  • The card entry methods supported by the reader (TAP, DIP, or SWIPE).
  • The Reader state.

You can use this information to send notifications to users of your application when a reader is unpaired or its battery is low. In case of a pairing error, you can use connectionInfo.failureReason to provide more details and suggestions to your application users about how to retry their pairing attempt.

Link to section

Getting reader updates

The Mobile Payments SDK reports changes to connected readers to any subscribed observers. An observer must conform to the ReaderObserver protocol and receives notifications when:

  • A reader starts or stops charging.
  • A reader's battery level changes.
  • Reader state changes (for example, starts connecting or becomes ready to take payments).
Link to section

Card input methods

Different reader devices offer different card entry methods. Square Reader for magstripe can only accept swiped cards, while Square Reader for contactless and chip can accept tapped or dipped cards. The card entry methods supported are available within the ReaderInfo supportedInputMethods. However, this list isn't updated if the available entry methods change (for example, if the NFC connection to a contactless reader times out). Your application should add an AvailableCardInputMethodsObserver to be notified when the available input methods change.

Before taking a payment, your application should display the available payment methods to customers as a prompt to swipe, insert, or tap their card to pay. The SDK provides a prebuilt payment prompt screen you can use instead of creating a custom prompt. If you want to create your own payment prompt screen, your application should query the PaymentManager availableCardInputMethods method and display the available payment methods to buyers.

Link to section

Reader state

Your application can check ReaderInfo.state to learn information about readers. You might want to display messages to users when a reader is actively connecting, updatingFirmware, or disconnected or if a reader failedToConnect.

If a reader’s state is ready, it's paired, connected, and able to accept card payments. For example, if you want to get the number of readers capable of taking payments, you can apply a filter to all connected readers.

import SquareMobilePaymentsSDK extension <#YourViewController#> { func readyReaderCount() -> Int { // You can access all connected readers via // `MobilePaymentsSDK.shared.readerManager.readers` MobilePaymentsSDK.shared.readerManager.readers.filter { $0.state == .ready }.count } }
Link to section

Unpairing a reader

Paired contactless and chip readers are remembered by the Mobile Payments SDK. When a new card reader is paired to the application, it remains paired until forgotten with the ReaderManager's forget(reader) method.

Link to section

Next steps

To test your application in the Square Sandbox without a physical Square Reader device, use the Mobile Payments SDK Mock Reader UI to simulate a reader and accept test payments. Otherwise, after you've paired a physical Square Reader device, you're ready to take payments in a production environment.