Checking POS Status

Before you initiate a transaction, you can verify if the Tap on Phone application is properly initialized and ready. To do this, you send a status request using an Android Broadcast.

This guide shows you how to request the current status of the Point of Sale (POS) and how to handle the response.

Step 1: Register a Broadcast Receiver

The Tap on Phone application processes your status request asynchronously and returns the result via a broadcast. You must register a BroadcastReceiver to listen for this response.

You can listen for the default response action (com.dejamobile.cbp.sps.STATUS_BROADCAST_RESPONSE) or define a custom action name.

// Define your broadcast action (default or custom)
val responseAction = "com.dejamobile.cbp.sps.STATUS_BROADCAST_RESPONSE"

val receiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
        val status = intent?.getStringExtra("Status") ?: "Unknown"
        val info = intent?.getStringExtra("Info") ?: ""

        when (status) {
            "Initialized" -> println("POS is ready to process payments.")
            "None" -> println("POS is not initialized. Call InitActivity first.")
            "Failed" -> println("The status request failed. Try launching the POS app and retry.")
            else -> println("Unknown status received.")
        }

        // Unregister the receiver once handled
        context?.unregisterReceiver(this)
    }
}

// Register the receiver
val filter \= IntentFilter(responseAction)
registerReceiver(receiver, filter)

Step 2: Send the Status Broadcast

Once your receiver is listening, construct and send the broadcast intent to request the status.

You must specify the Tap on Phone package and the StatusBroadcastReceiver class.

val intent = Intent().apply {
    action = "com.dejamobile.cbp.sps.STATUS_BROADCAST"
    component = ComponentName(
        "com.dejamobile.cbp.sps.app",
        "com.dejamobile.cbp.sps.app.broadcast.StatusBroadcastReceiver"
    )
    addFlags(Intent.FLAG_INCLUDE_STOPPED_PACKAGES)

    // Optional: Specify your custom response action
    // putExtra("ResponseAction", responseAction)
}

// Send the broadcast
sendBroadcast(intent)

Status Response Parameters

When your receiver catches the response, the intent contains several extras. The most important is the Status string, which dictates whether you can proceed with a payment.

Status Value	Meaning
`Initialized`	The POS app is successfully initialized and ready to process transactions.
`None`	The POS app is not initialized. You must launch the `InitActivity` before processing payments.
`Failed`	The request failed. Try opening the POS application manually and retrying.

If the status is Initialized, the response intent also includes the following optional extras:

merchantId: The current merchant ID.
userId: The current user ID.
merchantContractCode: The current merchant contract code.

Use the status broadcast to ensure the POS is ready when your application resumes (onResume). If the status returns None, redirect the merchant to your initialization flow.