Applies to: Mobile Payments SDK - Android
Learn how to pair and manage card readers with the Mobile Payments SDK for Android.
Applies to: Mobile Payments SDK - Android
Learn how to pair and manage card readers with the Mobile Payments SDK for Android.
Square Reader for magstripe is automatically detected by the 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 preconfigured reader settings screen you can use in your application by calling SettingsManager.showSettings()
. 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 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.
Pair a new reader using ReaderManager.pairReader()
. Only one reader pairing can be in progress at one time, so check the Boolean value ReaderManager.isPairingInProgress
and only begin pairing if it's false
. pairReader
consumes a callback
to notify your application when pairing completes. Use this callback to update waiting spinners or similar displays in your application and provide notifications to users based on whether reader pairing is successful.
fun pairReader() {
val readerManager = MobilePaymentsSdk.readerManager()
pairingHandle = readerManager.pairReader { result ->
when (result) {
is Success -> {
val readerFound = result.value
logPairingResult(readerFound)
}
is Failure -> {
logPairingFailure(result.errorCode, result.errorMessage)
}
}
}
}
fun onPause() {
pairingHandle?.stop()
}
The pairing callback is guaranteed to be called when pairing ends, even if no reader was successfully paired. When pairing completes, this callback's success
value is a Boolean for whether a card reader paired. If the value is true
a card reader was found, reported to the callback provided using setReaderChangedCallback
, and added to the list of paired readers accessed with ReaderManager.getReaders()
. A successful but false
result indicates a canceled pairing attempt. If pairing fails for any reason, the error description contains a PairingErrorCode
with details about the failure.
The Mobile Payments SDK also provides the setReaderChangedCallback
, which is called when the state of a reader changes. Use this callback to notify your application when magstripe readers are inserted or removed, contactless and chip readers are paired or disconnected with Bluetooth, or the battery level passes certain thresholds.
fun observeReaderChanges() {
val readerManager = MobilePaymentsSdk.readerManager()
callbackReference = readerManager.setReaderChangedCallback { event ->
val reader = event.reader
val change = event.change
val readerState = event.readerState
when (change) {
ADDED -> onReaderAdded(reader, readerState)
REMOVED -> onReaderRemoved(reader, readerState)
else -> onReaderChanged(reader, readerState, change)
}
}
}
fun onPause() {
callbackReference?.clear()
}
Paired readers are remembered by the Mobile Payments SDK, so when a new card reader is paired to the application, it remains paired and present in the list of readers provided by ReaderManager.getReaders()
. If your application wants to stop pairing before it completes, you can do so with the returned pairingHandle
by calling pairingHandle.stop()
.
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. You can create your own screens to display information about readers status or use a Square-provided settings screen for quick integration.
Different reader devices offer different card entry methods. For example, 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.supportedCardEntryMethods
. 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 register a callback with PaymentManager.setAvailableCardEntryMethodChangedCallback
to be notified when the available entries change. Before taking any payment, your application should query PaymentManager.getavailableCardEntryMethods()
and display the available payment methods to customers as a prompt to swipe, insert, or tap their card to pay.
private fun updateAvailableMethods(view: TextView) {
val paymentManager = MobilePaymentsSdk.paymentManager()
// Set up a callback to update the card entry methods when they change
callbackRef = paymentManager.setAvailableCardEntryMethodChangedCallback { methods ->
updateCardEntryMethods(view, methods)
}
// Update the card entry methods immediately
updateCardEntryMethods(view, paymentManager.getAvailableCardEntryMethods())
}
private fun updateCardEntryMethods(view: TextView, methods: Set<CardEntryMethod>) {
view.text = when (methods.size) {
0 -> "Reader not connected"
1 -> when (methods.first()) {
CardEntryMethod.SWIPED -> "Swipe to pay"
CardEntryMethod.CONTACTLESS -> "Tap to pay"
CardEntryMethod.EMV -> "Insert to pay"
}
// Etc..
}
}
Your application can check ReaderInfo.state
to learn information about contactless and chip readers and display updates and messages to users when readers are 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.
fun getReaders() {
val readerManager = MobilePaymentsSdk.readerManager()
val readers = readerManager.getReaders()
// Do something with the readers
val availableReaders = readers.filter {
it.state == Ready
}.size
val contactlessReaders = readers.filter {
it.supportedCardEntryMethods.contains(CONTACTLESS)
}
val specificReader = readers.find {
it.serialNumber == "4815162342LS815"
}
// Etc..
}
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.