Build on Android

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:

1. Install and configure the Mobile Payments SDK in your Android application
2. Authorize the Mobile Payments SDK
3. Pair a card Reader
4. Take a payment

For an example implementation, download the Mobile Payments SDK sample application, written in Kotlin using Compose.

• Your Square account is 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 in production (not required for sandbox payments).
• Your application's minSdkVersion is API 24 (Android 7) or later.
• Your application's targetSdkVersion is API 33 (Android 13) or a minimum of API 24 (Android 7).
• 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.
• 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.

The Mobile Payments SDK requires that the user grant access to their device’s current location while using your app. To use a Contactless and Chip reader to take card payments, Bluetooth must be enabled, and to use a magstripe reader, your application must be granted permission to access the device's microphone.

Ensure your application requests the following runtime permissions:

The Mobile Payments SDK isn't compatible with custom devices from original equipment manufacturers 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:

• The Mobile Payments SDK isn't supported for rooted devices or devices with custom ROMs.
• Square prohibits using any software that provides the ability to record or capture screen data or that results in elevated privileges.
• Square recommends running the Mobile Payments SDK on devices from large mobile device manufacturers such as Google or Samsung.
• If your mobile application runs on an uncommon device manufacturer, be sure to test the device with any expected software requirements, including Bluetooth connectivity, before investing in the device.
• Supported OS versions should be the latest or as close to the latest as possible.
• Review the Square support window for the OS version and confirm support for the compilation target version and the runtime version. The compilation target currently supports version 34. For runtime, the supported versions are 24 to 34.

Get started with the Mobile Payments SDK by configuring your Android application and taking a test payment in the Square Sandbox.

Follow the steps to set up and test the Mobile Payments SDK in your own application or download the Mobile SDK sample application (written in Kotlin) to see an example of initialization, authorization, and taking payments in production or the Square Sandbox.

Add Square's Maven repo to your project's settings.gradle file and the following dependencies to your project's build.gradle file. The Mock Reader UI is used to simulate virtual reader devices.

settings.gradle.kts:

...
dependencyResolutionManagement {
 repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
 repositories {
   ...
   maven ("https://sdk.squareup.com/public/android/")
 }
}
...

build.gradle.kts:

...
dependencies {
 // Your dependencies
 ...
 val squareSdkVersion = "2.0.2"
 // 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 Console 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 Console to the Credentials page. This page contains your Square application ID used to initialize the Mobile Payments SDK.

A good place to initialize the SDK is inside the onCreate() method of an extended Application class, because it's executed early in the application lifecycle.

class DemoApplication : Application() {
    override fun onCreate() {
      super.onCreate()
      MobilePaymentsSdk.initialize(getId(), this)
    }
}

If using the previous example, you should write your own implementation for getId() to return your application ID value from the Developer Console. Depending on your use case, this can be your production or Sandbox application ID, which might be stored as hardcoded strings, as Android resources, or fetched from your server.

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.

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 authorizationManager = MobilePaymentsSdk.authorizationManager()
    // Authorize and handle authorization successes or failures
    callbackReference = authorizationManager.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 automatically attaches a floating button to the currently displayed Activity as you navigate between screens in your application after you've called MockReaderUI.show(). The icon can be dragged anywhere on the screen and persists throughout your application lifecycle.

override fun onCreate() {
    super.onCreate()
    // If in Sandbox - display Mock Reader floating icon
    if (MobilePaymentsSdk.isSandboxEnvironment()) {
        MockReaderUI.show()
    }
}

// MockReader must hide once deauthorized as it should only be used within the Sandbox environment.
private fun deauthorize() {
    MockReaderUI.hide()
}

Click the following 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 button again to test your application's payment flow and simulate swiping, inserting, removing, or tapping a 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 button 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 PaymentParameters to represent details of an individual payment and PromptParameters to indicate how the payment prompts are presented to the buyer.

Before beginning a payment, create a PaymentParameters object. At a minimum, you must include the payment amount and an idempotency key. For the complete list of payment parameter values and details, see Android technical reference.

Each payment also requires PromptParameters, consisting of a mode and additionalPaymentMethods available to buyers. 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 prompting buyers to swipe, tap, or insert 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.

If you create your own custom payment prompt UI, use the setAvailableCardEntryMethodChangedCallback to update your UI if the available card entry methods change (for example, if a magstripe reader is inserted or removed from the mobile device). You should set this callback in either a ViewModel or an Activity’s onCreate() or onResume() method.

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 ->
        // Callback to handle the payment result
        when (result) {
            is Success -> // show payment details
            is Failure -> // show error message
        }
    }
}

override fun onDestroy() {
    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 Square 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.

• Authorize your Android Application
• Pair and Manage Card Readers
• Take a Payment