Applies to: Mobile Payments SDK - Android | Payments API | OAuth API
Learn how to build a secure in-person payment solution for Android devices with the Mobile Payments SDK.
Applies to: Mobile Payments SDK - Android | Payments API | OAuth API
Learn how to build a secure in-person payment solution for Android devices with the Mobile Payments SDK.
The Mobile Payments SDK offers developers a secure way to integrate the Square checkout flow into their mobile applications and accept in-person payments with Square Readers.
There are four steps required to take your first payment using the Mobile Payments SDK:
You have a Square account enabled for payment processing. If you haven't enabled payment processing on your account (or you're not sure), visit squareup.com/activation.
You have a Square Reader device to take payments.
Your application's minSdkVersion
is API 24 (Android 7) or later.
Your application's targetSdkVersion
is API 33 (Android 13) or earlier.
Your application's compileSdkVersion
is 34.
Your application uses AndroidX or enables Jetifier in gradle.properties
.
You're using the Android Gradle Plugin version 8.1.0 or later. The Mobile Payments SDK might work with 7.1.0 or later, but stability isn't guaranteed.
You're not using Proguard for code optimization. Compressing the Mobile Payments SDK binary removes critical bytecode elements and results in runtime errors.
Your version of the Mobile Payments SDK adheres to the Square update policy. To limit risk to developers and their users, Square enforces an update policy requiring developers keep their version of the Mobile Payments SDK current.
You're generally familiar with developing applications on Android. If you're new to Android development, you should read the Documentation on the Android Developers site before continuing.
To take payments with Square Readers, your application must request the following device permissions.
Android device permission | Purpose |
---|---|
ACCESS_FINE_LOCATION | To confirm that payments are occurring in a supported Square location. |
RECORD_AUDIO | To receive data from magstripe readers. |
BLUETOOTH_CONNECT | To receive data from contactless and chip readers. |
BLUETOOTH_SCAN | To store information during checkout. |
READ_PHONE_STATE | To identify the device sending information to Square servers. |
The Mobile Payments SDK isn't compatible with custom devices from OEMs that violate Square's security rules or devices that grant root access to the mobile device operating system code and kernel. These devices cannot connect to a contactless and chip reader and don't comply with Square's security requirements.
The following additional considerations apply when trying to run the SDK on custom devices:
Get started with the Mobile Payments SDK by configuring your Android application and taking a test payment in the Square Sandbox.
Add the Square Maven repo and the following dependencies to your project's build.gradle
file. The Mock Reader UI is used to simulate virtual reader devices.
repositories {
...
maven {
url "https://sdk.squareup.com/public/android"
}
}
dependencies {
// Your dependencies
...
def squareSdkVersion = "2.0.0-beta1"
// Mobile Payments SDK dependency
implementation "com.squareup.sdk:mobile-payments-sdk:$squareSdkVersion"
// MockReader UI dependency
implementation "com.squareup.sdk:mockreader-ui:$squareSdkVersion"
}
Before taking a payment or attempting any other operation with the Mobile Payments SDK, you must initialize it using the initialize
method and your Square developer application ID. To get your application ID, sign in to the Developer Dashboard and choose your application. If you don't have an application, see Get Started for steps to create a Square application.
Your application opens in the Developer Dashboard to the Credentials page. This page contains your Square application ID used to initialize the Mobile Payments SDK.
To test the Mobile Payments SDK in the Square Sandbox with mock readers and mock payments, switch the toggle at the top of the Developer Dashboard to Sandbox to show your Sandbox credentials and initialize the SDK with your Sandbox application ID. To start taking production payments, you must initialize the Mobile Payments SDK again with your production application ID.
class DemoApplication : Application() {
override fun onCreate() {
super.onCreate()
val appId = OAuthHelper.getAppId(this)
MobilePaymentsSdk.initialize(appId, this)
}
}
The AuthorizationManager
handles authorization for the Mobile Payments SDK. Call the authorize()
method with an OAuth access token and location ID. If you're testing your application in the Square Sandbox, you can use your Sandbox personal access token and location ID.
Don't deploy an application that contains your personal access token into production. For secure authorization in production, you should implement OAuth instead of using a personal access token.
In your call to authorize()
, configure a callback to be notified of authorization errors and display those to the user.
override fun onResume() {
super.onResume()
val authManager = MobilePaymentsSdk.authorizationManager()
// Authorize and handle authorization successes or failures
callbackReference = authManager.authorize(accessToken, locationId) { result ->
when (result) {
is Success -> {
finishWithAuthorizedSuccess(result.value)
}
is Failure -> {
when (result.errorCode) {
NO_NETWORK -> showRetryDialog(result)
USAGE_ERROR -> showUsageErrorDialog(result)
}
}
}
}
}
override fun onPause() {
super.onPause()
// Remove the callback reference to prevent memory leaks
callbackReference?.clear()
}
Physical card readers aren't supported in the Square Sandbox. To take test payments, you must simulate a virtual reader with the Mock Reader UI.
The Mock Reader UI consists of a floating action button (FAB) that automatically attaches itself to the currently displayed Activity as you navigate between application screens when you call MockReaderUI.show()
. The icon can be dragged anywhere on the screen and persists throughout your application lifecycle.
Click this button to simulate connecting a magstripe reader or a contactless and chip reader to your device. You can use the ReaderManager
to programmatically access information about these simulated readers, such as their model and available card entry methods.
When mock readers have been connected and you begin a payment, click the FAB again to test your application's payment flow and simulate a swiped, inserted, or tapped card with the mock reader. Click Payment details to select different card brands and payment behaviors (approved or declined) for testing purposes. To hide the FAB in your application, call MockReaderUI.hide()
.
To pair physical readers for production payments, see Pair and Manage Card Readers.
The PaymentManager
handles payments in the Mobile Payments SDK. Prior to starting a payment, you create a set of PaymentParameters
to represent details of an individual payment and a set of PromptParameters
to indicate how the payment prompts are presented to the buyer.
When setting up the payment, use the setAvailableCardEntryMethodChangedCallback
to notify your application whether the available card entry methods have changed (for example, if a magstripe reader was inserted or removed from the mobile device). You should include this callback in either a ViewModel
or an Activity’s onCreate()
or onResume()
method.
Before beginning a payment, create a PaymentParameters
object, which includes the payment amount, idempotency key, optional tip, application fee (if applicable), and the processing mode used if you want to take payments while offline. For the complete list of payment parameter values and details, see the Android technical reference.
Each payment also requires a set of PromptParameters
, consisting of a mode
and a set of additionalPaymentMethods
that buyers can use for a payment. At this time, KEYED
(a manually entered credit card payment) is the only additional payment method available.
Square provides a payment prompt screen that displays a UI to buyers prompting them to swipe, insert, or tap their card, depending on the payment options available. To use this screen, set PromptParameters.mode
to DEFAULT
. If you want to create your own custom payment prompt screen instead of using the default, set PromptParameters.mode
to CUSTOM
.
When you're ready to begin a payment, call PaymentManager.startPaymentActivity()
with the PaymentParameters
and PromptParameters
you created for this payment, along with a callback
to notify you of the payment's success or failure.
fun startPaymentActivity() {
val paymentManager = MobilePaymentsSdk.paymentManager()
// Configure the payment parameters
val paymentParams = PaymentParameters.Builder(
amount = Money(100, CurrencyCode.USD),
idempotencyKey = UUID.randomUUID().toString()
)
.referenceId("1234")
.note("Chocolate Cookies and Lemonade")
.autocomplete(true)
.build()
// Configure the prompt parameters
val promptParams = PromptParameters(
mode = PromptMode.DEFAULT,
additionalPaymentMethods = listOf(Type.KEYED)
)
// Start the payment activity
handle = paymentManager.startPaymentActivity(paymentParams, promptParams) { result ->
// Handle the payment result
when (result) {
is Success -> showPaymentDetails(result.value)
is Failure -> showPaymentError(result.errorCode, result.errorMessage)
}
}
}
fun onPause() {
handle?.cancel()
}
During a payment, Square takes control of the screen display as another Android Activity to ensure that buyer information is handled securely and that the final confirmation of the payment is correctly shown to the buyer.
If the payment completes successfully, a Payment
object is returned to your payment callback. This payment can be accessed on the Seller Dashboard or with the Payments API. If the payment fails, the response contains a PaymentError
.
After installing the Mobile Payments SDK and testing your application with test payments in the Square Sandbox, learn more about configuring your application to take production payments:
If you need more assistance, contact Developer and App Marketplace Support or ask for help in the Developer Forums.