Build and test your app

Follow the guidance below for Apps on Devices integrations.

Discover and connect a reader

private fun discoverReaders() {
    Terminal.getInstance().discoverReaders(
        config = HandoffDiscoveryConfiguration(),
        discoveryListener = object : DiscoveryListener {
            override fun onUpdateDiscoveredReaders(readers: List<Reader>) {
                // In handoff discovery, the list will
                // contain a single reader. Connect to
                // the reader after it is discovered.
                readers.firstOrNull()?.let { reader ->
                    connectReader(reader)
                }
            }
        },
        callback = object : Callback {
            override fun onSuccess() {
                // Handle successfully discovering readers
            }

            override fun onFailure(e: TerminalException) {
                // Handle exception while discovering readers
            }
        }
    )
}

private fun connectReader(reader: Reader) {
    Terminal.getInstance().connectReader(
        reader,
        HandoffConnectionConfiguration(
            object : HandoffReaderListener {
                override fun onDisconnect(reason: DisconnectReason) {
                    // Optionally get notified about reader disconnects (for example, reader was rebooted)
                }

                override fun onReportReaderEvent(event: ReaderEvent) {
                    // Optionally get notified about reader events (for example, a card was inserted)
                }
            }
        ),
        object : ReaderCallback {
            override fun onSuccess(reader: Reader) {
                // Handle successfully connecting to the reader
            }

            override fun onFailure(e: TerminalException) {
                // Handle exception when connecting to the reader
            }
        }
    )
}

Collect payments

After you connect to the reader using handoff mode, you can start collecting payments.

The Stripe Reader app handles payment collection and other payment operations, such as saving payment details. When initiating a payment operation, the Stripe Reader app becomes the primary and launches in full screen. Then, the Stripe Reader app guides the customer through the flow and returns control to your app after completion (success or failure) or customer cancellation. When control returns to your app, the Stripe Reader app continues to run in the background.

See an example of collecting payment in an Apps on Devices app.

Collect payments while offline Preview

Apps on Devices supports offline payment collection.

You can access the device’s admin settings by launching the stripe://settings/ deep-link URI from your app.

See an example of launching the admin settings deep-link URI.

startActivity(
    Intent(Intent.ACTION_VIEW)
        .setData(Uri.parse("stripe://settings/"))
)

Stripe doesn’t provide an application-level instrumentation solution. To keep track of crashes and other logs from your application, you can use a third-party library such as Sentry or Crashlytics.

The device user’s language selection (not country) informs the value returned by Locale.getDefault(). You can change the device language in the admin settings.

Stripe Android devices have the Auto-rotate screen setting enabled by default. Your app can override this setting by locking the UI to a specific screen orientation.

This can be achieved by setting the screenOrientation attribute on the relevant <activity> tags in the manifest.

<activity
    android:name=".MainActivity"
    android:screenOrientation="portrait">
</activity>

Alternatively, this can be set programatically using Activity::setRequestedOrientation in your Activity class.

class MainActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Lock to portrait orientation
        requestedOrientation = ActivityInfo.SCREEN_ORIENTATION_PORTRAIT

        // Or, lock to landscape orientation
        // requestedOrientation = ActivityInfo.SCREEN_ORIENTATION_LANDSCAPE
    }
}

Stripe Android devices don’t render a system UI, including a back button or status bar.

If your app needs to communicate battery level, charging state, and connectivity status to the user, refer to the following Android API docs for guidance:

• Monitor the Battery Level and Charging State
• Monitor connectivity status and connection metering

When the Stripe reader connects or disconnects from a dock, the Android operation system triggers a configuration change.

By default, your app’s activity is automatically recreated on a configuration change.

To disable automatic activity recreation when connecting to or disconnecting from a dock, add android:configChanges="uiMode" in the <activity> entry in your AndroidManifest.xml file.

<activity
    android:name=".MyActivity"
    android:configChanges="uiMode" />

Your activity can be notified of configuration changes by implementing Activity::onConfigurationChanged. This method is only called if you’ve specified configurations you want to handle with the android:configChanges attribute in your manifest.

class MainActivity : Activity() {
    override fun onConfigurationChanged(newConfig: Configuration) {
        super.onConfigurationChanged(newConfig)
        // implement custom configuration change handling logic
    }
}