Initializing the POS

Before you can process any payment transactions, you must initialize the Tap on Phone application. The initialization process establishes a secure session, triggers Single Sign-On (SSO) validation with your backend, and configures the terminal for the specific merchant.

You typically perform this initialization once when the merchant logs into your client application. The session remains active between app launches and device reboots until you explicitly reset it.

Prerequisites

Before you initialize the POS, ensure you have:

• The current userId, merchantId, and userToken for the authenticated merchant.
• Your organization’s ClientID, formatted as a JSON string.
• Implemented the AndroidX Activity Result APIs to handle the intent response.

Step 1: Register the Activity Result Launcher

The Tap on Phone app processes the initialization asynchronously and might display an interface to request necessary device permissions (such as location access) from the merchant.

You must register an Activity Result callback to handle the final outcome:

val posInitResult = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result ->
    if (result.resultCode == Activity.RESULT_OK) {
        // The POS is initialized and ready to process transactions
    } else if (result.resultCode == Activity.RESULT_CANCELED) {
        // The initialization failed
        val data = result.data
        val errorCode = data?.getStringExtra("errorCode") ?: "None"
        val errorName = data?.getStringExtra("errorName") ?: "None"
        val errorMessage = data?.getStringExtra("errorMessage") ?: "None"

        // Handle the error (e.g., prompt the user to retry or contact support)
    }
}

Step 2: Construct the Initialization Intent

Create an explicit Android Intent targeting the Tap on Phone application’s InitActivity. You must include the package name, the specific class name, and the mandatory parameters as intent extras.

1. Set the component class to com.dejamobile.cbp.sps.app.InitActivity.
2. Format your Client ID as a JSON string to pass into the operationMetadata extra.
3. Add the userId, merchantId, and userToken.

private fun startPosInit(userId: Int, merchantId: Int, userToken: String, clientId: String) {

    // Format the Client ID as a JSON string
    val operationMetadata \= "{\\"ClientID\\":\\"$clientId\\"}"

    val intent \= Intent().apply {
        setClassName(
            "com.dejamobile.cbp.sps.app",
            "com.dejamobile.cbp.sps.app.InitActivity"
        )

        putExtra("userId", userId)
        putExtra("merchantId", merchantId)
        putExtra("userToken", userToken)
        putExtra("operationMetadata", operationMetadata)
    }

    // Launch the intent
    posInitResult.launch(intent)
}

Step 3: Launch the Intent

Call your function to launch the intent.

When you launch this intent:

1. The Tap on Phone app sends the initialization request to the backend.
2. The backend sends an SSO permission request to your backend.
3. If your backend approves the request (HTTP 200), the Tap on Phone app configures the local terminal.
4. The Activity finishes and returns RESULT_OK to your registered callback.