Worldline Management Interface

Version 1.0.3

Table of Contents

1. Introduction

   1. Supplementary documentation

   2. Acronyms

   3. Tap on Mobile operation modes

      1. Standalone operation mode

      2. Integrated operation mode

      3. Operation modes summary

   4. Supported processes

      1. Checking ToM status outside WPI context

      2. ToM already registered with other application

      3. Integrated ToM registration process

      4. Integrated ToM deregistration process

   5. Interface limitations

2. [WMI] Android Communication Layer

   1. Android Inter App Communication

      1. Interface structure

      2. Android Intent implementation

3. [WMI] Integrated authentication functions

   1. Check application status

   2. Register terminal

   3. Unregister terminal

   4. Application statuses

   5. Result

   6. Service Types

4. Tap on Mobile backend API

   1. ToM backend API OAuth2 authentication

      1. Request Parameters

      2. Response Parameters

   2. Retrieving and managing merchant’s terminal structure

      1. Request Parameters

      2. Response Parameters

   3. Locking a terminal selected for registration

      1. Request Parameters

      2. Response Parameters

1. Introduction

This page is intended for third-party application providers who wish to develop business applications interacting with Worldline Tap on Mobile application and explicitly covers the supplementary management processes which currently are built around the integrated registration functions. All payment context uses cases and operations are defined by Worldline Payment Interface. All source code examples used in this document are written in Kotlin (Android). High level architecture and interfaces view including Worldline Payment Interface and Tap on Mobile Management Interface flows is presented below.

1.1 Supplementary documentation

1.2 Acronyms

1.3 Tap on Mobile operation modes

Due to regulatory constraints Tap on Mobile application uses a single and common distribution channel – Google Play Store. It means that all offered operation modes must be consistently supported in the same product. Hence, it is important to understand the dependencies between relevant operation modes, i.e. standalone and integrated authentication. Tap on Mobile application logic checks and relies on selected operation mode.

1.3.1 Standalone operation mode

Standalone operation mode represents all use cases in which the application has been manually enrolled by the user by the means of built-in UI registration options. This mode requires to establish a 4-digit application access code which entry is then required for any authentication operations. If supported by the current product configuration, access code may be replaced by the device biometry options.

Using standalone operation mode supports WPI methods. All WPI function calls to unauthenticated ToM application will trigger a login screen (4-digit access code or biometry means required). The only exception from this rule applies when product configuration specifically supports a delegated application login for WPI (setting is specific to standalone authentication mode).

In future releases ToM application logic for standalone mode operation will introduce a rule that will disable the manual application usage after the 1st processed WPI call. In this scenario: upon the manual launch the ToM application that already processed WPI calls will present a dedicated screen informing the user that it runs in an integrated mode.

1.3.2 Integrated operation mode

Integrated operation mode represents all use cases in which the application is enrolled using WMI. WPI functions are also supported for terminals using this mode, however there are several rules which are crucial for proper integrated mode usage and understanding, i.e.:

1. ToM application registered in integrated mode cannot be accessed from the application GUI (except login screen upon manual application launch);

2. After registering ToM application is responsible for its own authentication and session validity and hence login/authentication function does not need to be covered by 3rd party application;

3. During the registration process in integrated mode, ToM application checks the registering 3rd party application package name and bounds to it;

4. While ToM application is exclusively bound to certain 3rd party application package name, all WPI and selected WMI requests incoming from other application packages will be rejected with a dedicated errorCondition code;

   1. WMI_SVC_REGISTER service is exempted from this rule to allow automated re-bounding of ToM application to another 3rd party application package name running in the same device.

To allow assessing which action is required, WMI offers a dedicated function to retrieve the current ToM application status. It is strongly recommended to retrieve this information outside of payment acceptance context.

1.3.3 Operation modes summary

This section outlines ToM application behavior for selected functions in available operation modes.

1.4 Supported processes

Current interface design addresses thre processes that are relevant for 3rd party application developers

1.4.1 Checking ToM status outside WPI context

This process explains actors and operations’ sequence for assessing the current ToM application status

1.4.2 ToM already registered with other application

This process outlines actors and operations’ sequence for negative scenario where ToM application is already registered with other 3 rd party application package

1.4.3 Integrated ToM registration process

This process explains actors and operations’ sequence for new terminal registration

1.4.4 Integrated ToM deregistration process

This process explains actors and operations’ sequence for removing previously made terminal enrollment

1.5 Interface limitations

Potential future improvements:

• Implement a dedicated activity replacing a standalone login screen to guide the user who opened the ToM app manually;

• Implement a reverse intent interface which would redirect the user to 3rd party application in case ToM application is launched using a desktop icon

Potential future improvements:

• Implement a dedicated preparatory screen before triggering an QR code reader by ToM application;

• Implement a reverse intent interface which would redirect the user to 3rd party application in case ToM application is launched using a desktop icon;

2. [WMI] Android Communication Layer

2.1 Android Inter App Communication

Tap on Mobile Management Interface is using Intents in Android that are a means of communicating between components of an Android app, such as between Activities, Services, Broadcast Receivers, and Content Providers. An Intent object is used to describe what an app component should do, including the action to be performed and the data to be used.

Intent usage in Android for application integration can be broadly categorized into two types:

1. Explicit Intents: These intents are used to launch a specific component within the same app. The target component is specified explicitly in the intent. For example, starting an Activity from another Activity within the same app.

2. Implicit Intents: These intents do not specify the target component directly. Instead, they declare a general action to be performed and let Android resolve the target component based on the information provided in the intent. For example, sending an email or opening a web page. WMI is the implementation of this type of intent.

Intents can also carry data in the form of key-value pairs, called Extras, which can be used to pass data between components. By using intents, apps can delegate tasks to other components and take advantage of the existing Android framework to perform common actions.

2.1.1 Interface structure

Currently WMI version provides a single intent type that developers can use to build apps that work with the interface. Due to solution configuration process requirements, all operations fall to Display Action category, i.e. actions performed do not require user interaction but require starting of payment acceptance solution start, hence cannot be executed as a background process. The following table lists each intent, along with its purpose:

2.1.2 Android Intent implementation

The start of an operation is based on an intent. Each special transaction type has a set of parameters that are mandatory

val intent = Intent("com.worldline.management.action.PROCESS_OPERATION").apply{flags += Intent.
FLAG_ACTIVITY_REORDER_TO_FRONT}

This intent requires some extras:

The transaction request fields and examples per transaction type are explained in the subsequent sections

/**
* Example code snippet on how to send a WMI request and handle the response.
*/

class LoginActivity : AppCompatActivity() {

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

    private fun startWMIOperation(WMIRequestJson: String, serviceType: String)  {
        val intent = Intent("com.worldline.management.action.PROCESS_OPERATION").apply {
        putExtra("WMI_SERVICE_TYPE", serviceType)
        putExtra("WMI_REQUEST", WMIRequestJson)
        putExtra("SHOW_OVERLAY ", false) // when we don’t want the overlay
    }
        launcher.launch(intent)
    }

    private fun handleWMIResponse(intent: Intent) {
        val rawJsonResponse = intent.getStringExtra("WMI_RESPONSE")
        // Handle response
    }
}

As you can see in the above example, the transaction request is sent to the payment application as JSON. The final result of the transaction is returned from the intent started previously and needs to be handled based on the service type. The JSON format is described in chapter 3.

3. [WMI] Integrated authentication functions

This chapter describes the data exchange format, all requests and responses are described here. WMI is using JSON as data exchange.

3.1 Check application status

This function is intended to be used outside of payment acceptance context to determine the current Tap on Mobile application status and assess whether it is properly authenticated and ready to perform payment acceptance functions

Request:

WMI_REQUEST parameters: None - might be created for future use

Response

WMI_RESPONSE_ parameters

Error conditions

3.2 Register terminal

This function is intended to be used outside of payment acceptance context to determine the current Tap on Mobile application status and assess whether it is properly authenticated and ready to perform payment acceptance functions.

Request

WMI_REQUEST parameters

Response

WMI_RESPONSE_ parameters

Error conditions

3.3 Unregister terminal

This function is intended to be used only with already registered terminal. It allows to unregister the currently assigned TID from the mobile application instance.

Request:

WMI_REQUEST parameters: None - might be created for future use

Response

WMI_RESPONSE_ parameters

Error conditions

3.4 Application Statuses

3.5 Result

3.6 Service Types

4. Tap on Mobile backend API

Implementing Tap on Mobile integrated authentication mode requires integrating 3rd party application backend directly to ToM backend API. Storing OAuth2 access credentials directly in the mobile application not allowed.

This integration process requires covering the following areas:

1. ToM backend API oauth2 authentication;

2. The logic to retrieve and manage merchant terminals structure in 3rd party application backend;

3. The logic to lock free terminal selected for registration.

4.1 ToM backend API OAuth2 authentication

The Oauth2 token endpoint provides access tokens which are used to authenticate and authorize requests to protected resources as described in ToM API and subsequent sections.

To request an access token it is required to provide a valid client ID and client secret.

4.1.1 Request Parameters

The following parameters are used in the OAuth2 token endpoint (/oauth2/token).

4.1.2 Response Parameters

The response from the token endpoint will include a number of parameters

4.2 Retrieving and managing merchant’s terminal structure

Merchant applications access to ToM backend API should reflect the complete merchant organization structure. Organization structure uses up to three tier levels, i.e.:

• CONTRACT_ID

  • VAT_ID#1

    • MID#11

    • MID#12

    • […]

    • MID#1n

  • VAT_ID#2

    • MID#21

  • […]

  • VAT_ID#n

    • MID#31

    • MID#32

    • […]

    • MID#3n

CONTRACT_ID is optional and only used in case lower level tiers require aggregation;

VAT_ID is optional and only used in case lowe level tier requires aggregation;

MID is the lowest and most common merchant organization structure tier; TIDs are allocated on a MID level.

Merchant structure is always assigned and edited by the acquiring entity. However, merchant’s 3rd party application backend should be capable of retrieving this structure from ToM backend, track the potential changes in it and be capable of deciding which TID should be assigned during the registration process.

ToM API documentation lists several merchant level functions that may be used for terminal management, however a suggested function for retrieving current merchant terminal structure is POST /api/v1/terminals/search .

4.2.1 Request Parameters

Complete list of function request elements is available in ToM API specification . Tables below summarize most important parameters and function filters.

4.2.2 Response Parameters

Complete list of response elements is available in ToM API specification . Table below summarizes most important fields.

4.3 Locking a terminal selected for registration

Decision on TID selected for registration should be followed with registration token generation. Creating a registration token moves the TID to ‘locked’ status. It means that throughout the registration token validity, TID cannot be manually registered in standalone mode.

ToM API function for the registration token generation operation is POST /api/v1/terminals/{id}/registrationtoken , where id is a terminal UUID stored in ToM backend.

Important note : registration token’s expiry timestamp may be extended by calling POST /api/v1/terminals/{id}/registration-token/refresh ToM API function. This operation maintains previous token value and new validity timestamp is returned in the response.

4.3.1 Request Parameters

Complete list of request elements is available in ToM API specification . Table below summarizes most important fields

4.3.2 Response Parameters

Complete list of response elements is available in ToM API specification. Table below summarizes most important field