Quick Start: Your First Initialization

Before you can process any payments, your client application must initialize the Tap on Phone App. This initialization establishes a secure session, triggers the Single Sign-On (SSO) validation with your backend, and prepares the terminal.

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

This tutorial guides you through creating the InitActivity intent, passing the required parameters, and handling the result.

Prerequisites

Before you begin, ensure you have:

• Your Client ID, Merchant ID, User ID, and User Token. (You can use the sandbox test values provided in the Prerequisites and Configuration guide).
• Configured your backend to handle SSO requests, as described in Backend Integration: Handling SSO Requests.
• Integrated the AndroidX Activity Result APIs in your Android project.

Step 1: Prepare the operation metadata

To route the SSO request to your backend correctly, you must pass your Client ID in the operationMetadata extra. This field requires a valid JSON string.

Format your Client ID as a JSON string in your code:

// Replace with your actual Client ID or the sandbox test value
val operationMetadata = "{\"ClientID\":\"your-client-id-here\"}"

Step 2: Register the Activity Result Launcher

To handle the response from the Tap on Phone app, register an Activity Result callback. This callback listens for the completion of the initialization process.

val posInitResult = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result ->
    if (result.resultCode == Activity.RESULT_OK) {
        // Initialization successful. The POS is ready to process payments.
        println("SoftPOS Initialization completed successfully.")
    } else if (result.resultCode == Activity.RESULT_CANCELED) {
        // Initialization failed. Extract the error details.
        val data = result.data
        val errorCode = data?.getStringExtra("errorCode") ?: "None"
        val errorName = data?.getStringExtra("errorName") ?: "None"
        val errorMessage = data?.getStringExtra("errorMessage") ?: "None"

        println("Initialization failed: $errorName ($errorCode) - $errorMessage")
        // Manage the error and display options to your user
    }
}

Step 3: Launch the InitActivity Intent

Construct an Android Intent targeting the Tap on Phone application’s InitActivity. You must include the package name, class name, and all mandatory extras.

Create a function to build and launch the intent:

private fun startPosInit(userId: Int, merchantId: Int, userToken: String, operationMetadata: String) {
    val intent = Intent().apply {
        // Specify the Tap on Phone package and the InitActivity class
        setClassName(
            "com.dejamobile.cbp.sps.app",
            "com.dejamobile.cbp.sps.app.InitActivity"
        )

        // Add the mandatory extras
        putExtra("userId", userId)
        putExtra("merchantId", merchantId)
        putExtra("userToken", userToken)
        putExtra("operationMetadata", operationMetadata)
    }

    // Launch the intent using the registered callback
    posInitResult.launch(intent)
}

Step 4: Run and Verify

Call your startPosInit function using your sandbox credentials.

If the SSO validation succeeds and the device passes the initial security checks, the callback receives RESULT_OK. Your application is now ready to process transactions.

If you receive RESULT_CANCELED, check the returned errorCode and errorMessage. Common issues during initialization include network timeouts, incorrect Client IDs, or unauthorized responses from your SSO backend.

Next Steps

Now that you have successfully initialized the Tap on Phone application, you can explore the core concepts or move straight into processing payments.

• Understand the Architecture.
• Learn how to Process a Purchase Transaction.