B2B Terminal Registration
Document Version: 3.0
Register your mobile devices as payment terminals for Tap on Mobile.
Registration Process
Contact your Partner Manager for terminal credentials.
Enter the provided UMID and UTID in your application.
Complete activation to start accepting payments.
Get help with terminal registration
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.).
Android architecture
iOS architecture
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 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 the near future
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)
the option using username and password that was only available on iOS has been removed as of Q3'2025.
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.
Tap on Mobile Environments
Refer to Environments for available environments
Backend-to-backend activation
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
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, 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 credentials are linked to a user and we recommend to use a technical user instead of a personal user account. The client_id can be found 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
Overall terminal registration process (via API)
Terminal search request
When making a search for an available terminal, 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.
sample response to terminal search request
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 circle before the TID is empty, meaning the terminal is available for registration.
sample request for terminal registration
sampe response for terminal registration
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:
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.
Sample registration request with email parameters and body
The response is the same as without an email in the request.
sample response registration with email
For a sample of the email, see below: The QR-code can be scanned by the smartphone or the code can be entered manually.
Unregistering a terminal
Unregistering a terminal can be done using several ways:
- unregistration from the portal
- unregister within the app (SDK or WMI)
- unregister using merchant API (
POST /api/v1/terminals/{id}/unregister)
Warning: Terminal registration to a ToM-app targets a live-span of several months. The Terminal can be unregistered from that app and registered again to another app (on another device). However, registration and unregistration is not to be used on a per transaction or per day use. It is foreseen when a device needs to be replaced.
Reasons for this limitation are:
- History loss: Last transaction operation breaks, Device does not show history, Support in case of issues is very hard to trace
- Refunds: A refund on the device will be no longer possible
- Complexity of the operation: Each time a terminal is registered, secure generation and exchange of certificates is required
Below are some uses cases where the functions can be considered:
- Register at start of the service when terminal is not registered
- Unregister a terminal when not used for a couple of days
- Unregister a terminal when the device is broken or replaced
Below are some uses cases for which the functions are not meant:
- Register/unregister at every transaction
- Unregister after an inactivity of the app for some time
- Unregister/register when accepting payment for different merchants (use multi-merchant feature)
- Register always the same terminal when many others are available
Use cases
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.
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.
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.
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.
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 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.
- https://developer.android.com/guide/components/intents-filters - google description of intents
Document history
| Date | Version | Description | |
|---|---|---|---|
| 17/12/2024 | 0.0.1 | Initial version of this document | |
| 22/01/2025 | 0,0,2 | Added clarifications | |
| 23/01/2025 | 1.0 | Review and release version 1.0 | |
| 10/09/2025 | 2.0 | Use new activation process | |
| 23/09/2025 | 2.1 | Adjustments after feedback team | |
| 26/09/2025 | 2.2 | Feedback after review | |
| 02/10/2025 | 2.3 | Updated Terminal Search request body | |
| 12/10/2026 | 3.0 | Fill update for developer portal | |