Skip to content
Tunic Pay Documentation

Invoke a Prevent session using the Android SDK

The Android SDK enables your users to interact with Tunic Pay’s Prevent service during the payment journey. This guide will walk you through the steps to integrate the SDK into your app. You’ll learn how to:

  • Install and configure the SDK
  • Invoke a Prevent session in your payment journey
  • Handle callbacks and results

Before you start

You’ll need these things to run through this guide:

  • Android Studio installed on your development machine.
  • An existing Android application where you want to integrate the SDK.
  • Minimum Android SDK version: API 21 (Android 5.0 Lollipop) or higher.

1. Add the SDK to your project

Add the Maven Repository

Add the Tunic Pay SDK’s Maven repository to your project’s build.gradle file and the SDK dependency to your app’s build.gradle file:

/build.gradle
allprojects {
    repositories {
        google()
        mavenCentral()


        // Add Tunic Pay's Maven repository
        maven { url 'https://maven.tunicpay.com/repository/prevent/' }
    }
}
/app/build.gradle
dependencies {
    // ... other dependencies
    implementation 'com.tunicpay.prevent:android:0.4.0'
}

2. Configure the SDK

To use the SDK, you have to initialise it first before invoking any other SDK method.

The following example does so in the Application class:

App.kt
import com.tunicpay.prevent.config.Environment
import com.tunicpay.prevent.TunicPaySdk


class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()


        TunicPaySdk.initialize(context = this) {
            environment = Environment.PRODUCTION
        }
    }
}

Configuring the Backend Endpoint (optional)

If you need to point to a different backend endpoint (e.g., for testing or staging environments or to support non-standard deployment architectures), update the baseUrl in the Config object or set TP_BASE_URL to add a static URL at build time.

App.kt
TunicPaySdk.initialize(context = this) {
    environment = Environment.PRODUCTION
    baseUrl = "https://my-secure-api.example.com"
}

3. Invoke the Prevent session

Invoke the Prevent session at the point in your app where the user initiates a payment. This can be called conditionally based on your app’s logic, and the approach may differ if you’re using AndroidX Activity / Jetpack Compose / other frameworks.

Create a PaymentContext object

Prepare a PaymentContext object with the necessary payment details. These details are used to assess payment risk and to customize the prevent session to your user.

Payment.kt
import com.tunicpay.prevent.processing.PaymentContext
import com.tunicpay.prevent.model.CurrencyCode
import com.tunicpay.prevent.model.Money
import com.tunicpay.prevent.model.Party


val paymentContext = PaymentContext(
    externalIds = mapOf(
        "internal" to "your-unique-transaction-id",
        "someThirdParty" to "their-unique-case-id",
    ),
    amount = Money(100.00, CurrencyCode.GBP),
    creditor = Party.NaturalPerson(
        name = "Jane Smith",
        preferredName = "Jane",
        externalIds = mapOf(
            "internal" to "your-unique-party-id",
            "3p": "their-unique-party-id",
        ),
    ),
    debtor = Party.Account(
        accountNumber = "87654321",
        sortCode = "112233",
        name = "John Doe",
    ),
)

Start the Prevent session

Invoke the Prevent session using the launch method.

Payment.kt
// Other imports...
import android.widget.Toast
import com.tunicpay.prevent.processing.PreventContext
import com.tunicpay.prevent.processing.PreventActivityContract
import com.tunicpay.prevent.processing.PreventResult


// Payment context...


val contract = PreventActivityContract()
val preventSession = registerForActivityResult(contract) {
    when (it) {
        is SessionState.Resolved ->
            Toast.makeText(this, "Flow succeeded", Toast.LENGTH_SHORT).show()
        else ->
            Toast.makeText(this, "Flow failed", Toast.LENGTH_SHORT).show()
    }
}


val context = PreventContext(paymentContext = paymentContext)
preventSession.launch(context)

4. Handle the Results from the Prevent session

After invoking the Prevent session, you need to handle the result returned by the SDK. This includes processing successful completions, cancellations, and errors.

Register for Activity results

In your Activity or Fragment, register for the result of the Prevent session using the registerForActivityResult method and the PreventActivityContract.

Payment.kt
import android.os.Bundle
import android.widget.Toast
import androidx.activity.result.ActivityResultLauncher
import androidx.appcompat.app.AppCompatActivity
import com.tunicpay.prevent.processing.PreventContext
import com.tunicpay.prevent.processing.PreventActivityContract
import com.tunicpay.prevent.processing.SessionState
import com.tunicpay.prevent.processing.PaymentContext
import com.tunicpay.prevent.model.*


class MyActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)


        // Set up the context of the payment
        val paymentContext = PaymentContext(
            externalIds = setOf("your-unique-transaction-id"),
            amount = Money(100.00, CurrencyCode.GBP),
            creditor = Party.NaturalPerson(
                name = "Jane Smith",
                preferredName = "Jane",
                externalIds = setOf("your-unique-party-id"),
            ),
            debtor = Party.Account(
                accountNumber = "87654321",
                sortCode = "112233",
                name = "John Doe",
            ),
        )


        // Register for the activity result
        val contract = PreventActivityContract()
        val preventSession = registerForActivityResult(contract) {
            when {
                it is SessionState.Resolved         -> handleSuccess(result)
                it.error is UserError.Abandoned     -> handleCancellation(result.error)
                else                                -> handleError(result.error)
            }
        }


        val context = PreventContext(paymentContext = paymentContext)
        preventSession.launch(context)
    }


    private fun handleSuccess(result: SessionState.Complete) {
        // The flow was completed successfully. This doesn't mean the payment is
        // low-risk; check the result for more details.
        Toast.makeText(this, "Flow finished", Toast.LENGTH_SHORT).show()
        // Continue with your payment journey logic
    }


    private fun handleCancellation() {
        // The flow was aborted by the user before completion.
        Toast.makeText(this, "Flow was cancelled by the user.", Toast.LENGTH_SHORT).show()
    }


    private fun handleError(error: Throwable) {
        // Handle errors, e.g., network issues, server errors
        Toast.makeText(this, "An error occurred: ${error.message}", Toast.LENGTH_LONG).show()
    }
}