Applies to: Mobile Payments SDK - iOS | OAuth API | Locations API
Learn how to pair and manage card readers with the Mobile Payments SDK for iOS.
Applies to: Mobile Payments SDK - iOS | OAuth API | Locations API
Learn how to pair and manage card readers with the Mobile Payments SDK for iOS.
Square Reader for magstripe is automatically detected by Mobile Payments SDK when inserted or removed from a device's connection port. Square Stand contains a built-in reader device and doesn't need an external paired reader to take payments. However, Square Reader for contactless and chip requires Bluetooth pairing. The Mobile Payments SDK's ReaderManager
handles this pairing and provides ways to monitor changes in Square readers.
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.
The Mobile Payments SDK offers a pre-made reader settings screen you can use in your application by calling SettingsManager.presentSettings()
. This screen includes two tabs. The Devices tab displays the model and connection status for readers paired to your application, 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. You can also use the SettingsManager
to programmatically retrieve information about the current sdkEnvironment
(either production
or sandbox
) and the current sdkVersion
.
If you want more control over your reader pairing and management screens, you can create your own using information from the Mobile Payments SDK ReaderManager
. This manager provides methods for pairing and forgetting readers, accessing information about a particular reader, and listening for reader status updates.
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
.
import SquareMobilePaymentsSDK
class <#YourViewController#>: UIViewController {
private var pairingHandle: PairingHandle?
func startPairing() {
// `self` must conform to ReaderPairingDelegate
pairingHandle = MobilePaymentsSDK.shared.readerManager.startPairing(with: self)
}
func stopPairing() {
// Manually stop searching for nearby readers.
pairingHandle?.stop()
}
}
extension <#YourViewController#>: ReaderPairingDelegate {
func readerPairingDidBegin() {
print("Reader pairing did begin!")
}
func readerPairingDidSucceed() {
print("Reader Paired!")
}
func readerPairingDidFail(with error: Error) {
// Handle pairing error
print("Error: \(error.localizedDescription)")
}
}
The ReaderInfo
class provides information about Square readers paired with your application. These properties include:
TAP
, DIP
, or SWIPE
).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 ReaderInfo.connectionInfo.failureReason
to provide more details and suggestions to your application users about how to retry their pairing attempt.
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:
import SquareMobilePaymentsSDK
class <#YourViewController#>: UIViewController {
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
// Add this class as an observer to receive reader updates.
MobilePaymentsSDK.shared.readerManager.add(self)
}
override func viewDidDisappear(_ animated: Bool) {
super.viewDidDisappear(animated)
MobilePaymentsSDK.shared.readerManager.remove(self)
}
}
extension <#YourViewController#>: ReaderObserver {
func readerWasAdded(_ readerInfo: ReaderInfo) {
print("Reader Added!")
}
func readerWasRemoved(_ readerInfo: ReaderInfo) {
print("Reader Removed!")
}
func readerDidChange(_ readerInfo: ReaderInfo, change: ReaderChange) {
switch change {
case .batteryDidBeginCharging:
print("Reader is charging.")
case .batteryDidEndCharging:
print("Reader not charging")
case .batteryLevelDidChange:
print("Reader battery changed to: \(readerInfo.batteryStatus!.level)")
case .stateDidChange:
print("Reader state changed to:\(readerInfo.state)")
@unknown default:
// Handle other `ReaderChange` events here.
print(change)
}
}
}
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 a reader's 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 any payment, your application should query PaymentManager.availableCardInputMethods()
and display the available payment methods to customers as a prompt to swipe, insert, or tap their card to pay.
import SquareMobilePaymentsSDK
import UIKit
class <#YourViewController#>: AvailableCardInputMethodsObserver {
var availableCardInputMethods = MobilePaymentsSDK.shared.paymentManager.availableCardInputMethods
func viewDidLoad() {
// Add this class as an observer to receive updates to
// available card input methods.
MobilePaymentsSDK.shared.paymentManager.add(self)
}
public func availableCardInputMethodsDidChange(_ cardInputMethods: CardInputMethods) {
availableCardInputMethods = cardInputMethods
if availableCardInputMethods.isEmpty {
print("No card readers connected.")
} else {
print("Available card input methods: \(cardInputMethods)")
}
}
}
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
}
}
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 ReaderManager.forget(reader)
.
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.
If you need more assistance, contact Developer and App Marketplace Support or ask for help in the Developer Forums.