The Worldline Payment Interface (WPI) is an Android intent-based interface that enables easy and fast integration with payment apps. It is designed to allow additional business applications to execute payments on any Worldline offered SmartPOS device. A SmartPOS device is a payment device that runs Android And also smartphones using Tap On Mobile..

All Worldline Payment Solutions support WPI, which means that business applications that use this interface can run everywhere without any change of code. This makes it easy for developers to build payment apps that are compatible with a wide range of payment devices and payment protocols.

The WPI interface is built on top of the Android Intent mechanism, which allows different parts of an app to communicate with each other in a structured way. By using intents to trigger payment-related actions, the WPI interface simplifies the payment integration process and makes it easier for developers to build business applications on top of Payment Solutions.

What You'll Learn

• Send a request using the WPI V2.X interface
• Handle the response
• Create a simple business app that launches payment

Get the code

Click the following link to download all the code for this codelab:

Download Zip

Check out the sample app

For this codelab we will use Android studio Narwhal Feature Drop, SDK 36 and Gradle 8.14.3Important Please verify that you have a payment application running on your device.

The code you just downloaded contains code for all codelabs available. To complete this codelab, open the samplecode project inside Android Studio.

The codelabs repo contains starter code for all codelabs in the pathway. For this codelab, use the wpiCodelab project.

• wpiCodelab — Project that contains the start and finished code for this codelab.

The project is built with two app folders:

• start – the starter code for this project; you will make changes to this to complete the codelab.
• finished_code – contains the solution to this codelab.

We recommend that you start with the code in the start folder and follow the codelab step-by-step at your own pace.

During the codelab, you'll be presented with snippets of code that you'll need to add to the project. In some places, you'll also need to remove code that is explicitly mentioned in comments on the code snippets.

Getting familiar with the code and running the sample app

Take a moment to explore the project structure and run the app.

When you run the app from the ‘start' folder , you'll see that this is a very simple application with only a text field to enter an amount and a button to proceed to the payment.

For this codelab we will see how to implement a payment but the WPI provides a set of intents that developers can use to build apps that work with the interface. The following table lists each intent, along with its purpose:

Learn more about Android Messenger Service

Extras

An extra in Android intents is a way to pass additional data or parameters to another component in order to provide more context or information for the requested action. In WPI we have extras for request and response. The request extras needs to be provided by the Business Application that is using the interface and the response extra is provided by the Payment Solution.

Request:

Response:

• Financial

• Management

Data Dictionary

Payment Request Data:

Response Data:

Important: If your app targets Android 11 (API level 30) or higher, you must declare the external intents your app queries in your AndroidManifest.xml using the queries element. Without this, your app will not be able to discover or interact with payment solutions using WPI intents.

Add the following to your AndroidManifest.xml (outside the tag):

<queries>
    <intent>
        <action android:name="com.worldline.payment.action.PROCESS_INFORMATION" />
    </intent>
    <intent>
        <action android:name="com.worldline.payment.action.PROCESS_TRANSACTION" />
    </intent>
    <intent>
        <action android:name="com.worldline.payment.action.PROCESS_MANAGEMENT" />
    </intent>
</queries>

This ensures your app can query and interact with payment solutions using the WPI interface on Android 11+.

Creation of the request

Create a new data class SaleTransactionRequest in the package com.worldline.wpi_codelab.model.request. This class takes 2 parameters: the currency and the amount as these are the only mandatory parameters for a sale transaction.

@Serializable
public data class SaleTransactionRequest(
    val currency: String,
    val requestedAmount: Long,
)

To use the Serialization you need to add the following code in your gradle.app:

plugins {
    id("kotlinx-serialization")
}

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.9.0")
}

To finish sync your project with Gradle files.

Creation of the response

Create a second data class SaleTransactionResponse in the package com.worldline.wpi_codelab.model.response. This class takes 3 parameters: the result the currency and the amount. We can serialiaze more fields of the response based on the table of response data but, for this codelab we will only use these 3 fields.

@Serializable
data class SaleTransactionResponse(
    val result: String?,
    val authorizedAmount: Long? = null,
    val currency: String? = null,
)

In the MainActivity we will execute the transaction and handle the response. To do so we will use a registerForActivityResult.

To have more information about how to get a result from an activity you can click here.

executeSaleTransaction

The first method will be executeSaleTransaction and it will execute the registerForActivityResult:

• We use the WPI Version 2.1 but you can use the latest version supported by your payment provider.
• We generate a random UUID for the session id

private fun executeSaleTransaction(amount: Long) {
    val saleTransaction = SaleTransactionRequest("eur", amount)
    val saleTransactionJson: String = Json.encodeToString(saleTransaction)

    val intent = Intent("com.worldline.payment.action.PROCESS_TRANSACTION")
    // These extras are mandatory whether the intent comes from the payment
    // application or a 3rd party application.
    intent.putExtra("WPI_SERVICE_TYPE", "WPI_SVC_PAYMENT")
    intent.putExtra("WPI_REQUEST", saleTransactionJson)
    intent.putExtra("WPI_VERSION", "2.1")
    // Session value is always up to the third party application
    // Random unique identifier of the current communication session
    // Can be used to restore the state of the transaction in multipart communication (e.g. product delivery)
    intent.putExtra("WPI_SESSION_ID", UUID.randomUUID().toString())
    
    launcher.launch(intent)
}

handleTransactionResponse

The second method will be handleTransactionResponse:

//allows ignoring fields we don't need in the response
private val json = Json { ignoreUnknownKeys = true }

private fun handleTransactionResponse(intent: Intent) {
    val rawJsonResponse = intent.getStringExtra("WPI_RESPONSE")
    if (rawJsonResponse != null) {
        Log.d("Transaction response", rawJsonResponse)
        val transactionResponse = json.decodeFromString<SaleTransactionResponse>(rawJsonResponse)
        val paymentMessage = "${transactionResponse.result}: ${(transactionResponse.authorizedAmount?.toDouble()?.div(100))} ${transactionResponse.currency}"
        Toast.makeText(this, paymentMessage, Toast.LENGTH_SHORT).show()
    }
    // Handle response
}

launcher

To finish this step, just add to your main activity the launcher that will handle the result of the activity when you perform a payment:

private val launcher = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
) { result ->
    result.data?.let { handleTransactionResponse(it) }
}

Now that everything is set up, we will make the payment start by pressing the button.

As the amount formating is not the subject of this codelab, we use a simple solution with radio buttons and pre-defined amount.

To finish on this codelab, just add the executeSaleTransaction function in the onSubmit of your SaleTransactionScreen Composable:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContent {
        SaleTransactionScreen { amount ->
            executeSaleTransaction(amount)
        }
    }
}

Here we check which radio is checked and we lauch executeSaleTransaction with the selected amount.

You can now run the app on a terminal and proceed to your first payment.

Congratulations, you've successfully completed this codelab and learned how to proceed to a payment with the WPI!

You learned about how to create a request, a response, and how to use the Worldline Payment Interface.

What's next? Check out the others possible transactions in the documentation and try to handle them.