Backend-to-Backend Activation

Version 2.3

Table of Contents

1. Introduction

   1. About Tap on Mobile

   2. Supplementary documentation

   3. Acronyms

   4. Tap on Mobile integration modes

   5. Activation options

2. Tap on Mobile Environments

3. Backend-to-Backend Activation

   1. Main characteristics of B2B activation

   2. Pre-requisites to start using B2B activation

   3. Swagger file

   4. Overall terminal registration process (via API)

   5. API authorization

      1. Request Parameters

      2. Response Parameters

   6. Terminal search request

   7. Transaction search request

   8. Assigning selected terminal to an application

   9. Assigning selected terminal to an application with email

   10. Use case: terminal not registered

   11. Use case: terminal already activated

   12. Android specifics

   13. iOS specifics

4. Retrieving and managing merchant's terminal structure

1. Introduction

The goal of this document is to explain backend-to-backend (B2B) activation for Tap on Mobile on Android and iOS. B2B activation is always used when operating in integrated mode regardless of using app-to-app or SDK mode. It is also used when third party backend would like to obtain information from acceptance system (like transactions / configuration etc.).

1.1 About Tap on Mobile

Worldline Tap on Mobile is Worldline’s mobile payments solution that lets a merchant accept contactless payments using a smartphone instead of a traditional card terminal.

What it typically means:

• A merchant installs a Worldline-enabled app on an Android phone (with NFC) or iPhone and uses the phone to accept contactless payments from cards or mobile wallets.

• The phone acts as the payment terminal, connected to Worldline’s payment processing platform, and funds settle to the merchant’s account.

Key points:

• For merchants: lowers hardware costs and lets you accept card-present payments with just a supported smartphone.

• For consumers: you can pay by tapping your card or mobile wallet on the merchant’s phone screen or on a compatible terminal.

• Availability varies by country and region, and setup usually requires a Worldline merchant account and internet access.

1.2 Supplementary documentation

1.3 Acronyms

1.4 Tap on Mobile Integration modes

Tap on Mobile can be integrated in several operating modes:

• App-to-app: this is the easiest way to integrate and uses Intents 1 on Android. This requires at least two apps; Tap on Mobile and the partner or merchant app. See WPI and WMI documentation for more information.

• SDK: the SDK is integrated with the partner app, this requires more development skills to make it work but brings the best user experience and only requires one app. Refer to the SDK documentation for more information. This solution is only available for iOS for now.

• More to come in 2026

1.5 Activation options

Several options to activate a terminal are offered:

• Using online portal with Challenge and Response code (default mode for non-integrated merchant)

• Activation using QR-code (available on Android with version 5.9 and on iOS with app and SDK 1.7.

• Backend-to backend activation (via API - active on iOS and Android)

Note 1

The option using username and password that was only available on iOS has been removed as of Q3’2025.

Note 2

This document only describes the new activation flow that is supported as of Android mobile app version 5.9 and iOS SDK 1.7. The previous registration method is no longer documented although it will continue to be supported for some time. For iOS, this deprecated registration method will continue to be supported with SDK 1.7 but support will stop with SDK 1.8 and beyond.

This document only covers backend-to backend activation.

2. Tap on Mobile Environments

Tap on Mobile connectivity depends on the location since Worldline uses different tenants depending of the region and very tenant has its own backend.

There are three levels of environments available:

• Sandbox : this is meant for developing and testing partner applications and integrations. There is no financial flows involved and the transactions are processed by a mock.

• Pre-production : this is identical to production and mainly used for L3 tests and only exceptionally used by partners that integrate with Tap on Mobile. Transactions are processed by a scheme simulator.

• Production : this is where real money flows occur (authorizations on the card related bank accounts) and used in the shops by merchants.Connected with global payment card infrastructure.

Every acquirer has its own portal and users, url can be found below. Users are assigned per acquirer and per environment. A user can have different levels: merchant (MRC), acquirer (ACQ) or admin (ADM)

Sandbox:

Production:

Access to selected environment is given based on separate request.

3. Backend-to-Backend activation

3.1 Main characteristics of B2B activation

The main characteristics of B2B activation are:

• Activation handled by merchant backend and merchant app

• No additional UI needed

• No manual interaction needed

• Partner backend to be authenticated by Worldline backend

• Available for iOS and Android

3.2 Pre-requisites to start using B2B activation

The pre-requisites to start using B2B activation:

• User account at the backend was created (based on request to the acquirer)

• Merchant ID (MID) assigned to the merchant

• Terminals configured in backend for the merchant

• Oauth2 credentials defined for the every environment

• Swagger file (documenting of API)

• Business app supporting B2B activation

• Business server supporting B2B activation

For a user account, a merchant id, terminals and Oauth2 credentials, please reach out to the integration team using the following email: tom_integration@worldline.com

The user account consists of a user name and password.

The Oauth2 credentials consist of a client_UUID and client_secret. These creentials are linked to a user and we recommend to use a technical user instead of a personal user account. The client_id can be founr in the portal. OAuth2 credentials are linked to an environment , so you need separate credentials for sandbox and production.

Example

client_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

client_secret: xxxxxx

3.3 Swagger file

Tap on Mobile backend API specification can be found in the swagger file . This swagger file is a machine-readable description of all available API and defines what the API offers and how to use it.

Attention

If the API are not displayed , make sure to have /v3/api-docs in the search bar at the top of the screen

This swagger file is only available on the Worldline EU sandbox environment, but applies to all acquirers and environments. Behind every API, there is a label that indicates the type of access that is needed to use the corresponding API; MRC for merchant level users, ACQ for acquirer level and ADM for admin.

Some of the most common API are:

• POST /api/v1/users/info : obtaining current context and permissions of the users

• POST /api/v1/transactions/search; find transaction(s) based on input filtering criteria

• POST /api/v1/transactions/export/csv : export transactions in CSV format based on filter

• POST /api/v1/merchants/search

• POST /api/v1/devices/search

• POST /api/v1/users/search

• POST /api/v1/terminals/{id}/registration-token: Generate or retrieve registration code for terminal

• POST /api/v1/terminals/{id}/registration-token/refresh:

• DELETE /api/v1/terminals/{id}/registration-token/revoke

• POST /api/v1/terminals/search: look for available terminals

• POST /api/v1/terminals/{id}/unregister: Unregister Terminal from Device

• POST /api/v1/transactions/{id}/pdf-receipt: get a pdf-receipt for a specific transaction ID

• POST /api/v1/transactions/{id}/email-receipt : send a receipt by email for a specific transaction,

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

Example parameters used in many request types:

3.4 Overall terminal registration process (via API)

3.5 API Authorization

The authorization is based on OAUTH2 standard ( https://oauth.net/2/ OAuth 2.0 is an authorization framework that lets a user grant a third-party application limited access to their resources on a server, without giving that app their login credentials. After obtaining the token for the used credentials, all API that are accessible with the level for the user can be used. We refer to the received token as access_token.

3.5.1 Request Parameters

The following parameters are used in the OAuth2 token endpoint (/oauth2/token). First you need to obtain the OAUTH2 token to use for further requests:

POST {{{baseUrl}}/oauth2/token

{

“grant_type”: “client_credentials”,

“client_id”: “client_d”,

“client_secret: “client_secret”

}

According to RFC 6749 – grant_type should be sent in headers with x-www-form-urlencoded

Authorization handled can be BASIC (based on client_id and client_secret) as standard approach or alternatively with JWT certificates.

3.5.2 Response Parameters

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

{{baseUrl}} – is the path to the environment ie. https://sandbox-wl-emea.softpos.eu

Example response:

{

"access_token": "eyJraWQiOiI4MDBhIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiI5NjQ0MDU5Yy

1jN2MyLTQ5YTYtOTI0MS01NDQ3ZmY3MTlmZDkiLCJhdWQiOiI5NjQ0MDU5Yy1jN2MyLTQ5YTYtOTI0MS01NDQ3ZmY3MTlmZDki

LCJuYmYiOjE2NjE4NTU2NDUsInNjb3BlIjpbIm9wZW5pZCIsInZwb3MiXSwiaXNzIjoiaHR0cHM6XC9cL3VhdC5zb2Z0cG9zLm

V1XC9vYXV0aDIiLCJleHAiOjE2NjE4ODU2NDUsImlhdCI6MTY2MTg1NTY0NSwianRpIjoiMGFkNjI3ZGUtMmRlMC00YjAzLTlj

MTctZDM5NGQwZTUxODcwIn0.THq49cdFIcg8mBfRpruZDrEebB66_5_uzu7zRm4p8jj63u0XULSG6POS6y4iJAFBS3XBVbclt5

h4bSbXE9pvA8BMfYsr6R-

HUvvprNvSyJqZNUQCaag7vZzKR0IoOv7DuRk2EaE0KhDnP5kYVxtwE90b3ArLh7mCHV26mZpE9i5q-

v0q2uAO2MKriCVG7G1xxINZPiUfU-n-jwiGcrXGy7sZT1_au4M8IP_jSDpozhZYLPoYixuxc8vnejULc8yiaU3z-

BQbgnExPtdB6em6pkYfXvtcuff6SkuU-bp3o1jHeGV4 0WxtQ9taVCBLx8T-sZqvIGKmf-ljiv_oxaqF4g3AJBVxama-

fuceuncJKoHwgBHqcByEyFTkdRVugd6Wo_t-b8Gyw1WxEMsr1p3mUWbI5qM0OkjdOD-

JSX9PJZWox6EoARq0Bll1NQFCSKftlg9i5XtDGlj7dTk94gA2ZosA-8IwASdR_Ar-

i_aOL8MEu7g_DPOZXRCvENYmfS8v0BamUqfyEWFLmx575mpyvV6pRPLGMBRdU3cfR4ekXSNO1XRpFXFt3cSX0SuD8jZYH2lIN9

gdF5T7Fvgmi8bFqbVNYxY-7DtNcLyj0B_KIz_grx9uPYSp_9xTiQdxy48alREmZc2kQVUGejka8loeeF6lZrJXC-

p5sLMUJdpXE",

"scope": "openid vpos",

"token_type": "Bearer",

"expires_in": "29999"

}

This token must be attached to each request to the API in authorization header.

3.6 Terminal search request:

When making a search for an available temrinal, several filters can be added to the request body. below is a sample terminal search request. If the OAuth2 credentials are linked to multiple merchant ID, id_merchant has to be specified, connected to find a terminal that is not yet in use and active_registration to assure that the registration process has not yet started.

Response to sample request:

3.7 Transaction search request

Sample transaction search request

Response to transaction search request

API is equipped with pagination mechanism, x-total-count parameter in the header provides total number of records returned in whole set. Only the records accessible by the user permissions and the context are returned.

If multiple records are returned (it can be checked with , x-total-count parameter in the response header) and their number is higher than page limit, then you need to obtain next set of records increasing current number of records page (as input url parameter).

Each object inside the system has its own unique ID, based on UUID format (as defined in RFC 9562 ).

3.8 Assigning selected terminal to an application

Once an available terminal has been selected, a registration token can be requested from the backend using the API call POST /api/v1/terminals/{id}/registration-token , where id a terminal UUID stored in ToM backend.

The structure of the UUID is a standard UUID (Universally Unique Identifier) format of 32 hexadecimal characters, representing a 128-bit number, formatted as xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. These five groups are divided into 8, 4, 4, 4, and 12 hexadecimal digits, respectively, with hyphens separating the groups. Each 'x' represents a hexadecimal digit (0-9 or a-f), which can be upper or lower case.

Important note : this function is applicable only to not connected terminals. An attempt to assign already connected terminal will result with a “Terminal already used” response message (with http error 409). In this case it is also possible to deregister such terminal – releasing it for further registration with /terminals/unregister method

Before making the request, the terminal will look like this in the portal

The response contains the activationToken, creation date and expiration time. Looking at the sample above, this token is valid for 4 hours. This means that it gives the merchants 4 hours the time to activate the terminal. When integrated, activation will normally occur within less than a minute.

If for any reason, the expiration can be refreshed using the API call POST /api/v1/terminals/{id}/registration-token/refresh

The response is the same as for the initial token request

Once the token is returned, the status of the terminal at the portal changes to a solid filled circle in front of the TID, see below:

There is also a possibility to revoke the activation request using the API call DELETE /api/v1/terminals/{id}/registration-token/revoke

If this succeeds, the TID is again free and is shown as such in the portal:

3.9 Assigning selected terminal to an application with email

The case described in the paragraph 3.8 requires no interaction from the user. There is however also an option to send an email to the user with a QR-code that allows to activate the device. The request has one optional argument, this is an email that can be used to send an mail with the activation code.

Request parameters and body

The response is the same as without an email in the request.

Response

For a sample of the email, see below:

The QR-code can be scanned by the smartphone or the code can be entered manually.

3.10 Use case: terminal not registered

This use case is when the app is installed, reinstalled or unregistered and the terminal UUID is not known . This covers the complete flow.

3.11 Use case: terminal already activated

This use case occurs when the app was closed or the device restarted but the terminal has been registered before.

In this case, no interactions with the backend are needed.

3.12 Android specifics

Although the flow is identical on Android an iOS and the interface with the backend is the same, the detailed implementation is a bit different. Android uses the WMI Intent and below are the service types for activation.

WMI_SVC_CHECK_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.

WMI_SVC_REGISTER

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.

WMI_SVC_AUTH_UNREGISTER

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.

For more detailed information on Android specific implementation, see the WMI specification document.

3.13 iOS specifics

Although the flow is identical on Android an iOS and the interface with the backend is the same, the detailed implementation is a bit different. iOS uses the SDK and below are the specific functions for activation.

isDeviceRegistered()

This function doesn't require any parameter inputs and is used to confirm if a device is already registered

verifyRegistrationToken()

Validates the one-time registration code supplied, ensuring the registration process can begin. This function requires one parameter: registrationToken:

beginTokenRegistration()

Initiates the token registration process for the terminal, preparing the device to be securely assigned and enrolled as a payment terminal. This function requires one parameter: registrationToken

endTokenRegistration()

Completes the token registration process and activates the terminal. This final step finalizes the assignment and securely enables the device to function as a payment terminal. This function requires two parameters: registrationToken: and pin:

getTerminalID()

Retrieve the terminal Id of the terminal used in the current device.

For more detailed information on iOS specific implementation, see the iOS SDK specification document.

4. 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; terminals (defined by uuid values and 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.