WPI and WMI

Introduction

This documentation is intended for third-party application providers who wish to develop business applications interacting with Worldline Tap on Mobile application to provide contactless card payment functionality and covers the supplementary management processes which currently are built around the integrated registration functions.

High level architecture and interfaces view including Worldline Payment Interface and Tap on Mobile Management Interface flows is presented below.

To interact with a payment application, Tap on Mobile offers intent based interface for easy and fast integration. A 3rd party application is used to extend and control the business flow for the desired use cases. The payment application is displayed only in the event of a transaction. Tap on Mobile is using Android Intents mechanism that allows to communicate between components of an Android app, such as 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. Softpos API 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.

More information about Intents can be found in native Google Android documentation.

Tap on Mobile provides a set of intents that developers can use to build apps that work with the interface. The following intents are available:

• WPI Financial operations - offers the possibility of performing a financial operation: payment, reversal, refund, credit
• WPI Information operations – offers the ability to check the status of the last performed transaction
• WMI - provides a set of management functions necessary to register and unregister the application, as well as to check its current status

Notice: To fully utilize WPI's capabilities, backend-to-backend integration may also be required. This enables full remote management of the available terminals.

Wordline Management Interface (WMI)

Intent: com.worldline.management.action.PROCESS_OPERATION

The Tap on Mobile application, after installation and before first use, requires completing a registration process, which is intended to link the installed application with a specific payment terminal defined in the payment system.

The registration process can be carried out manually in the application by the user or in an integrated mode using the functions available within the Wordline Management Interface intent.

WMI offers the following services:

Service type	Description
WMI_SVC_CHECK_STATUS	Service type for checking current Tap on Mobile application status
WMI_SVC_REGISTER	Service type for initiating the terminal enrollment sequence
WMI_SVC_AUTH_UNREGISTER	Service type for unregistering the terminal by the 3rd party application package used previously for enrollment

More information about WMI

WPI Financial operations

Intent: com.worldline.payment.action.PROCESS_TRANSACTION

The Wordline Payment Interface – Financial Operations intent, as the name suggests, groups the services responsible for carrying out financial transactions.

It offers the following services:

Service type	Description
WPI_SVC_PAYMENT	Service type for a purchase
WPI_SVC_CANCEL_PAYMENT	Service type for a reversal of a previous transaction
WPI_SVC_REFUND	Service type for a refund of a previous transaction or for credit operation

WPI Information Operations

Intent: com.worldline.payment.action.PROCESS_INFORMATION

The Wordline Payment Interface – Information Operationd intent groups additional informational functions.

It offers the following services:

Service type	Description
WPI_SVC_LAST_TRANSACTION	Used to return the last (previous) transaction result. In case of the last payment transaction response is not known any more, it can be requested by this service. It will return the last financial transaction response independent of the result, failed or success. This is a recovery feature as the payment solution will remember the last SESSION_ID as well as corresponding transaction response.

Versioning

Wordline Payment Interface (WPI)

The WPI uses versioning with the format Y.X (e.g., 1.0, 2.1) to track and manage different releases of our software.

• Y (Major Version): Signifies a significant milestone with potential breaking changes. Example: a version 2.x request cannot be used with version 1.x.
• X (Minor Version): Represents a release with new features or improvements that should be backward compatible within the same major version. But there are exceptions to this - version 2.2 is not fully compatible with version 2.1

The published version of the documentation describes WPI version 2.2.

Tap on Mobile application versions supports following WPI versions:

Tap on Mobile Version	WPI 1.0	WPI 2.0	WPI 2.1	WPI 2.2
2.1.25 - 2.1.29	YES	-	-	-
2.1.30 - 2.1.33	YES	YES	-	-
2.1.34	YES	YES	Partially supported in terms of DCC	-
4.1.35	YES	YES	YES	-
Since 5.4.0	YES	YES	YES	YES

NOTICE: In the first quarter of 2025, version 1.0 of WPI will be phased out.

Wordline Managment Interface (WPI)

WMI is not versioned. Full downward compatibility is maintained as new functionality is added.

Before you start integration

Before starting the development certain preconditions need to be met, i.e.:

• 3rd party app developers should have an access to sandbox Worldline Tap on Mobile application;
• 3rd party app package needs to be whitelisted in sandbox environment;
• Organization structure for test merchant should be configured in sandbox environment;
• OAuth2 access credentials for ToM backend need to be provisioned and exchanged;

Tap on Mobile package names (Worldline Acquiring entities use different mobile application package names):

Acquirer	Android Package name	Region of availability
Worldline EU	eu.softpos.softposwrapper.wl	European Union
Worldline CH	eu.softpos.softposwrapper.wl	Switzerland
CAWL	eu.softpos.softposwrapper.cawl	France
Crédit Agricole	eu.softpos.softposwrapper.cawl	France
Payone	eu.softpos.softposwrapper.payone	Austria; Germany
KB Smart	eu.softpos.softposwrapper.kb	Czechia
ANZ Worldline	eu.softpos.softposwrapper.wlanz	Australia
ING Italy	eu.softpos.softposwrapper.ingit	Italy

Security remarks

Android permissions and settings

As default – the required Android permissions for running the application are set during the installation and registration process. But if the device works under MDM (or similar) types of management software, make sure that required permissions are set up properly.

List of required permissions used (may be extended in future versions of the application):

• NFC (exclusive access to read contactless cards)
• CAMERA (block the screen in case of PIN providing + entropy RNG seeding)
• GEOLOCATION_CHECK + ACCESS_FINE_LOCATION (verification of the transaction's location)
• INTERNET (communication with the host)
• ACCESS_NETWORK_STATE (verification of the network state)
• ACCESSIBILITY_SERVICE (recognizing overlapping apps)

Some vendors may have their own settings that may prevent application running (i.e. Xiaomi application popup windows blockade). Please consult the acquirer in case of problems with proper parameterization of the devices.

Device cannot have debug mode turned on or be rooted (works at standard user settings) – otherwise the error must be reported.

Device has also proper time and date set up. Best to be synchronized with any time server or GSM operator time. If time differs from the real one, then communication with the server will be refused.

System baseline and configuration

Devices running the application should be compliant with Google guidelines Please ensure that:

• Device is equipped with Hardware Backed Key-Store (aka “safe memory”) – most modern devices after 2018 should have such element
• Device supports GMS services and up-to-date Google Play services are installed
• Android version is still supported, and all newest security patches are installed
• In case of controlled/closed networks – the connection to the server and to Google service servers are turned on/allowed at firewall.
• Device has valid Google certificates uploaded
• Integrity API confirms that device can be used as payment solution  

Secure installation of payment app from the store

The softpos application is distributed via official Google Store. (https://play.google.com/) New version of the app issued is provided by dedicated URLs (consult with the acquirer, to have proper one) and available in official app store application. Please use the last available versions, having the newest security fixes and new functionalities.

Application has own update policy, that may be set-up by acquirers at any time. It will force the application to update during next start.

Certifications and security settings will be uploaded during first registration of the device. Refer to registration procedure in your application manual.

Application doesn’t need any special treatment as for the initial parameterization (the required permissions will be set-up during registration process – with step by step process). It is not possible to turn off any security settings from the application level. All required configuration is built-in to the application package, and only limited number of changeable parameters are uploaded at the start of the application.

Solution is secured by strong cryptography – all the data exchange, processes, payment related operations are handled within the defined security context. Certificates and keys distribution is done automatically via registration process. It is possible to unregister the device from backend level (via portal), which means removal of all cryptography materials and returning the application to initial state. Repeating of the registration process is then needed to reinitiate secure channels to the backend.

Application has own mechanisms to automatically update old certificates, so if it is regularly used, there’s no need to do any special operations even if the cryptographic certificates are changed at backend level.

Any manipulation of the data managed by the app and tries to break security measures inside the application or hardware keystore may lead to blacklist the device and unability to continue the payment operations on it.

If payment application is to be used with any 3rd party application, then make sure it is also installed securely (i.e. via Google Play) or in controlled environments (i.e. inside MDM managed networks). Only intent handling permissions is needed to initiate the operations with payment application.

If your application works in such called “overlay mode” (overlapping the other apps of the screen when running), it may be recognized by the payment app and the operations will be terminated. Please consult with the acquirer if such situation occurs.

3rd party application shouldn’t require perimissions higher than regular user of the device. Rooted devices will be recognized by payment application and you may not continue the operations.

NFC usage restrictions

If the 3rd party application uses the NFC interface, it may collide with the need to obtain exclusive access by the payment application. Due to regulatory and security reasons, NFC reader must be exclusively locked by payment application – and it is released after finishing the payment operation. 3rd party app must consider such behavior and release the NFC access before payment operation is made.

Tap on Mobile operation modes

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

Standalone operation mode

In standalone operation mode, the application has been manually enrolled by the user via the built-in UI registration options. This mode requires the user to establish a 4-digit application access code, which is then required for any authentication operations. If supported by the current product configuration, the access code can be replaced by device biometric options.

Standalone operation mode is blocked for user when:

• application was registered using WMI,
• application was registered manually and any financial operation was performed using WPI. This rule can be switched off using merchant configuration, but this is not recommended. In this case, after launching the application, a dedicated screen will inform the user that it is running in integrated mode.

Integrated operation mode

The integrated operation mode encompasses 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 crucial rules for the proper usage and understanding of integrated mode, i.e.:

1. The ToM application registered in integrated mode cannot be accessed from the application GUI (except the login screen when launched manually);

2. After registration, the ToM application is responsible for its own authentication and session validity, so the login/authentication function does not need to be covered by a third-party application;

3. During registration in integrated mode, the ToM application checks the package name of the third-party application being registered and binds to it;

4. While the ToM application is exclusively bound to a certain third-party application package name, all WPI and selected WMI requests incoming from other application packages will be rejected with a dedicated error condition code.

   Notice: The WMI_SVC_REGISTER service is exempt from this rule, allowing the ToM application to be automatically redirected to another third-party application package running on 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.

Operation modes summary

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

	Standalone operation mode (manual registration)	Integrated operation mode (WMI registration)
Manual desktop application launch	- ToM login screen (for unauthenticated app)<br><br>- ToM home screen (for authenticated app)	- ToM login screen <br><br>- dedicated screen informing that the application runs in an integrated mode
WPI functions	Supported (for whitelisted package names)	Supported only for 3rd party application package name that registered the ToM application
ToM application login upon calling WPI functions	- [global behavior] seamless – ToM app uses 4 digit access code set during registration or during 1st login activity; <br><br>- [optional behavior upon request] ToM login screen and manual provision of 4 digit access code every time the authentication is required	- Not applicable; handled internally by the ToM application
Manual desktop launch after calling WPI functions	- [global behavior]: dedicated screen informing the user that ToM application is running in an integrate mode<br><br>- [optional behavior upon request]: ToM login screen (for unauthenticated app)<br> ToM home screen (for authenticated app)	- dedicated screen informing that the application runs in an integrated mode
Unregistration capabilities	No WPI requests processed:<br><br>- Unsubscribe option available from login screen (for unauthenticated app);<br><br>- Unregister function in app settings (for authenticated app);<br><br>- Unregistering from merchant portal;<br><br><br><br>WPI requests already processed:<br><br>- Unsubscribe option available from a dedicated screen informing the user that ToM application is running in an integrated mode;<br><br>- Unregistering from merchant portal;	- WMI_SVC_AUTH_UNREGISTER function; <br><br>- WMI_SVC_REGISTER function (available to all 3rd party packages and purging the previous registration process); <br><br>- Unsubscribe option available from login screen (for unauthenticated app); <br><br>- Unregistering from merchant portal;

Implementation scaling

The following chapters describe core processes such as checking application status and the sequences required for registering and unregistering terminals via specific WMI service types. Communication between the third-party application and Tap on Mobile is handled through Android Intents and structured JSON data payloads, including defined error conditions and response statuses.

Tap on Mobile (ToM) operates in two main modes: standalone and integrated. Based on operating modes and merchant hierarchical structures, we can divide implementation scalability into small, medium, and large implementations based on the complexity of the requirements.

Small-scale

A small-scale implementation applies to individual terminals (TIDs) or simple MIDs, and utilizes the Standalone operation mode, which is characterized by manual enrollment and reliance on the user to handle authentication directly through the Tap on Mobile (ToM) application's built-in user interface.

A small-scale implementation can be devided into following phases:

• Enrollment and Authentication: Enrollment is performed manually by the user using built-in UI registration options. This mode requires establishing a 4-digit application access code, which is then required for authentication operations, or biometry options if supported by the product configuration.
• WPI Support: Using standalone mode supports Worldline Payment Interface (WPI) methods. Any WPI function call to an unauthenticated ToM application will trigger a login screen (requiring the 4-digit access code or biometry). <br>For Worldline in the Client App there is defined dynamic properties api.intent.passcode which, when set to TRUE, enables automatic login. It works as follows:
  • When logging into the application for the first time, the access code is saved in the application itself.
  • When the intent is triggered, if the access code is already saved, the Client application logs in automatically, and the Merchant no longer needs to enter it.
• Integration: This implementation requires little to no direct integration with the Tap on Mobile backend API, as management (registration/authentication) is handled internally by the ToM application's UI.

The diagram below illustrates the flow for initiating a transaction (WPI) in the Standalone operation mode, focusing on the critical manual authentication step required when the ToM application is unauthenticated.

Medium-scale

A medium-scale implementation relies on the ToM integrated operation mode, and can be completed in two ways, using QR Code Scanning or Direct Token Provisioning (Automated Scale). <br>In both ways, to generate a registrationToken that will later be sent to the Client App, the Client Backend performs the same steps as Backend authentication and Terminal Locking.

Backend Authentication: <br>The Client Backend obtains an access_token from the Tap on Mobile (ToM) backend API using OAuth2 authentication. <br><br>Terminal Locking: <br>The Client Backend retrieves the merchant's terminal structure (using /api/v1/terminals/search) and selects a Terminal ID (TID) to register it, then calls the API function POST /api/v1/terminals/{id}/registration-token to lock the TID and generate a unique registrationToken.

<br>Then, depending on the implementation method, the following steps are performed:

Implementation Using QR Code Scanning

1. The Backend needs to display this token, potentially encoded in a QR-code format, for the user to access. <br>(Note: The API function POST /api/v1/terminals/{id}/registration-token includes an optional email parameter to share the registrationToken in QR-code format via email, but this is an optional user notification and not the standard registration mechanism)
2. Registration Request (Missing Token): The Client App initiates the terminal registration sequence using WMI_SVC_REGISTER without providing the registrationToken parameter in the WMI_REQUEST.
3. ToM App Response: In this scenario, because the registrationToken parameter is not present, the Tap on Mobile (ToM) application will automatically launch a QR code scanner to collect the required permissions and scan the registrationToken.
4. Merchant Action: The Merchant then scans the QR code containing the token, allowing the ToM application to complete the registration process.
5. Tap on Mobile is registerd and ready to precess WPI actions.

    The diagram below illustrates the flow Medius-scale implementation via QR Code scans.

<br> <br> <br> Direct Token Provisioning

1. Token Delivery (Direct): The Client Backend transmits the generated registrationToken (which is a mandatory request parameter) to the Client App running on the device
2. Terminal Registration: The Client App initiates the enrollment sequence using the Worldline Management Interface (WMI) service WMI_SVC_REGISTER, passing the received registrationToken in the WMI_REQUEST parameters.
3. ToM App Response: In this scenario, because the registrationToken parameter is not present, the Tap on Mobile (ToM) application will automatically launch a QR code scanner to collect the required permissions and scan the registrationToken.
4. Merchant Action: The Merchant then scans the QR code containing the token, allowing the ToM application to complete the registration process.
5. Tap on Mobile is registerd and ready to precess WPI actions.

    In this method terminal management is centralized in the backend, and registration is initiated programmatically via WMI.

    The diagram below illustrates the flow Medius-scale implementation via QR Code scans

Large-scale

Implementation for a large-scale deployment using the Integrated Operation Mode is achieved through detailed backend integration, primarily revolving around the Integrated ToM registration process and comprehensive usage of the Worldline Payment Interface (WPI).

The integrated mode is mandatory for scaling, as it automates terminal management and bypasses the limitations of manual setup.

Large-scale implementation is achieved as follows:

1. Backend Integration for Centralized Management

Large-scale implementation necessitates direct integration between the 3rd party application backend and the Tap on Mobile (ToM) backend API. This integration covers the following mandatory areas:

• Authentication (OAuth2): The backend must handle OAuth2 authentication to obtain access tokens. These tokens are required to authenticate and authorize requests to protected resources within the ToM API. Storing these credentials directly in the mobile application is not allowed.
• Terminal Structure Retrieval: The backend must retrieve and manage the merchant’s complete terminal organization structure (including potentially hierarchical tiers like CONTRACT_ID, VAT_ID, and MID) using the function POST /api/v1/terminals/search. This allows the system to track potential changes and make decisions on which Terminal ID (TID) to assign during registration.
• Terminal Locking and Token Generation: To ensure controlled deployment, the backend must lock a free terminal selected for registration by calling the API function POST /api/v1/terminals/\{id}/registration-token. This action generates a unique registrationToken and moves the TID to a 'locked' status, ensuring the TID cannot be manually registered in standalone mode during the token's validity.

2. Device Enrollment and Binding

Once the backend generates the registrationToken, the Client App uses the Worldline Management Interface (WMI) to register the device:

• Token Delivery: The Client Backend delivers the generated registrationToken to the Client App.
• WMI Registration: The Client App initiates the terminal enrollment sequence using the service type WMI_SVC_REGISTER, passing the registrationToken.
• Exclusive Binding: During this registration process, the ToM application performs a crucial security check: it checks and exclusively binds to the package name of the registering 3rd party application. This binding ensures that all Worldline Payment Interface (WPI) and most WMI requests originating from other applications on the same device are rejected.

3. Operational Features Enabling Scale and Reliability

The Integrated operation mode provides features essential for running a large, complex network of payment terminals:

• Autonomous Authentication: After successful registration, the ToM application becomes solely responsible for its own authentication and session validity. The 3rd party application is thus relieved of managing user login or authentication functions for transactions.
• WPI Usage: The 3rd party application interacts with the ToM app using WPI function calls (e.g., WPI_SVC_PAYMENT) to execute all financial and management use cases, ensuring compatibility across a wide range of devices and payment protocols.
• Reliability and Recovery: For maximum reliability in a large network, the business application must store the WPI_SESSION_ID for every transaction request. If a transaction fails unexpectedly (e.g., due to an app crash or network error) and the result is unknown, the recovery feature WPI_SVC_LAST_TRANSACTION must be used to retrieve the outcome of the previous transaction from the payment solution.
• Device Unregistration: Large-scale terminal lifecycle management requires a simple way to decommission devices. This is done programmatically using the WMI service type WMI_SVC_AUTH_UNREGISTER, which removes the currently assigned TID and purges all previous enrollment data, making the device available for re-registration.

The diagram below illustrates a Large-scale implementation.

Worldline Payment Interface (WPI)

Finacial operations

Interface structure and activity launch

The WPI provides a set of intents that developers can use to build apps that work with the interface.

For financial transaction purpose com.worldline.payment.action.PROCESS_TRANSACTION intent should be used.

Type	Category	Intent	Purpose
Financial	Display Action - these actions start the payment solution that are processing financial transactions or require user interaction.<br>Notice: Android intents are used	com.worldline.payment.action.PROCESS_TRANSACTION	Process a financial transaction

Here is intent creation code:

    public Intent formatPurchaseRequest(String sessionId, WpiPurchaseRequest req) \{
        String json = GSON.toJson(req);

        Intent intent = new Intent("com.worldline.payment.action.PROCESS_TRANSACTION");
        intent.addFlags(Intent.FLAG_ACTIVITY_REORDER_TO_FRONT);
        intent.putExtra("WPI_SERVICE_TYPE", "WPI_SVC_PAYMENT");
        intent.putExtra("WPI_REQUEST", json);
        intent.putExtra("WPI_VERSION", "2.2");
        intent.putExtra("WPI_SESSION_ID", sessionId);
        intent.putExtra("SHOW_OVERLAY ", false)

        return intent;
    }

Intent contains a set of extras and needs to have FLAG_ACTIVITY_REORDER_TO_FRONT set.

Extra	Descritpion	Type	Condition
WPI_SERVICE_TYPE	Specify the subtype of action to be executed:<br>- WPI_SVC_PAYMENT - Service type for a purchase <br><br>- WPI_SVC_CANCEL_PAYMENT - Service type for a reversal of a previous transaction <br><br>- WPI_SVC_REFUND - Service type for a refund of a previous transaction	String	Mandatory
WPI_REQUEST	The request contains JSON structured data that is mandatory for the given service type.<br><br> The JSON structure is described in the following chapters for each function.	String	Mandatory
WPI_VERSION	Used WPI version (current: 2.2)	String	Mandatory
WPI_SESSION_ID	Used as an identifier of a WPI exchange (a request/response) between a client application and a payment application. Is used to recover the status of the exchange in case of an unexpected failure. Is provided by the client.<br>The session id:<br><br>- must be unique <br><br>- must not be reused for subsequent requests (as soon as the cache is expired this would not be an issue, so it is not necessary to keep track of it but as a general rule a unique random string per request should be used)<br><br>If an unexpected failure occurs during an exchange, the session ID can be used to allow the client to restore its state and synchronise the exchange status with the payment application.	String	Mandatory
SHOW_OVERLAY	The flag controls whether a transparent overlay (false) or a spinner (true) should be displayed at the start of the intent.	Boolean	Optional

To launch intent registerForActivityResult method should be used. In the response, the intent returns the following data.

Extra	Descritpion	Type	Condition
WPI_SERVICE_TYPE	Specify the subtype of action to be executed	String	Mandatory
WPI_RESPONSE	The response contains JSON structured data processed for the requested service type	String	Mandatory
WPI_VERSION	Used WPI version	String	Mandatory
WPI_SESSION_ID	Identifier of a WPI exchange provided by the client.	String	Mandatory

And here is response parsing sample code:

    public WpiPurchaseResponse parsePurchaseResponse(ActivityResult result) \{
        if (result.getResultCode() == Activity.RESULT_CANCELED) \{
            throw new RuntimeException("Intent cancelled.");
        }
        if (result.getResultCode() != Activity.RESULT_OK) \{
            throw new RuntimeException("Invalid result code: " + result.getResultCode());
        }

        Intent intent = result.getData();
        if (intent == null) \{
            throw new RuntimeException("Received intent without bundled data");
        }

        String json = intent.getStringExtra("WPI_RESPONSE");

        WpiPurchaseResponse resp = GSON.fromJson(json, WpiPurchaseResponse.class);
        resp.setSessionId(intent.getStringExtra("WPI_SESSION_ID"));

        return resp;
    }

Please remember
The important thing to note is that ToM can only handle one intent invocation at a time (of any intent type — it doesn’t matter whether it’s a financial or informational function). Therefore, it is crucial to make the next request only after receiving the response from the previous one.

<!-- If you want to see what a sample working code looks like, you can use the projects below.

Programming language	Project
Compose	https://gitlab.softpos.eu/samples/wpi-example-compose
Flutter	https://gitlab.softpos.eu/samples/wpi-example-flutter
Java	https://gitlab.softpos.eu/samples/wpi-example-java
Kotlin-compose	https://gitlab.softpos.eu/samples/wpi-example-kotlin-compose
Kotlin-XML	https://gitlab.softpos.eu/samples/wpi-example-kotlin-xml
-->

Payment

The Service Type for a purchase transaction is WPI_SVC_PAYMENT.

Prerequisites:

• ToM application correctly installed.
• Terminal properly registered (paired with the ToM backend system).
• Transaction parameters (currency, etc.) must be in accordance with the terminal profile.

WPI_REQUEST - list of supported input parameters

In WPI_SVC_PAYMENT, at a minimum, the currency and requested amount are needed. The full list of parameters is described in the table below.

Field name	Description	Type	Condition
currency	Currency of the amount. Alpha code value is defined in ISO 4217 (e.g. EUR)	String	Mandatory
requestedAmount	Total payment amount as minor unit. The fractional digits are evaluated based in the currency. For example, 11.91€ must be sent as 1191 and the currency as EUR. <br><br>(tip amount is excluded)	Integer	Mandatory
tipAmount	The tip amount to be used as minor unit. This amount has the same currency as the transaction amount.<br><br> For more information check 3.1.5.3 Tipping	Integer	Optional
reference	Reference (external transaction id) to be sent to the payment solution for reconciliation<br><br>Due to the limitation of acquiring systems, only following characters are supported: ('a'..'z', 'A'..'Z', '0'..'9', hex 40 - hex FF) <br><br>max. length of this field is 30 characters	String	Optional
receiptFormat	Transaction confirmation format. The possible options are a set of data in JSON format to build the confirmation, a text-based confirmation, or displaying the transaction confirmation in the application.<br><br> For more information check 3.1.5.1 Receipt Format	Array	Optional
onBehalf	Multi-merchant mode - on behalf transaction flag<br><br> For more information check 3.1.5.2 Transactions on Behalf	Boolean	Optional – required when transaction should be performed ‘on behalf’ in multi-merchant mode.
partnerTid	Multi-merchant mode - partner terminal TID<br><br> For more information check 3.1.5.2 Transactions on Behalf	String	Conditional
partnerMid	Multi-merchant mode - partner terminal MID<br><br> For more information check 3.1.5.2 Transactions on Behalf	String	Conditional
partnerTerminalUuid	Multi-merchant mode - partner terminal UUID<br><br> For more information check 3.1.5.2 Transactions on Behalf	String (UUID)	Conditional
partnerTerminalExtId	Multi-merchant mode - partner terminal external Id<br><br> For more information check 3.1.5.2 Transactions on Behalf	String	Conditional
checkoutId	Checkout identifier<br><br> For more information check 3.1.5.4 Checkouts	String (UUID)	Optional – required when merchant operates under acquirer configured with checkout verification.

WPI_RESPONSE - list of supported output parameters

Field name	Description	Type	Condition
result	Result of the transaction:<br><br>- WPI_RESULT_SUCCESS In case of successful transaction<br><br>- WPI_RESULT_FAILURE In case of failed transaction<br><br>	String	Mandatory
errorCondition	Specific error reason <br><br> For more information check 3.3 Error codes and proper error handling	String	Mandatory
remark	Terminal / transaction specific message for detailed error descriptions. Text provided by payment app.	String	Conditional – only for NOT successful transaction
actionCode	Specific action to be performed by the business application (always returned WPI_ACTION_CODE_NONE)	String	Conditional – only for successful transaction
timestamp	Date and time of the transaction, indicated by the acquirer. <br><br> Format according to ISO 8601	String (ISO 8601	Conditional – only for successful transaction
currency	Currency code of the transaction. Alpha code value defined in ISO 4217 e.g. EUR	String	Conditional – only for successful transaction
authorizedAmount	Amount of the transaction. The fraction is taken from the currency code. <br><br>Example: <br>Currency = EUR <br>requestedAmount = 3190<br>=> 31,90 €	Integer	Conditional – only for successful transaction
brandName	Brand name of used payment method <br><br> For more information check Appendix C.1 Brand Name	String	Conditional – only for successful transaction
customerLanguage	The merchant’s default language (set in the merchant’s data)<br><br>Format according to ISO 630-1 (alpha-2 code)	String	Conditional – only for successful transaction
applicationIdentifier	Payment card application identifier dependent on the used card e.g. for MasterCard A00000041010	String	Conditional – only for successful transaction in which a payment card was used
applicationLabel	Payment card application label, depending on the used card e.g. MasterCard DEBIT	String	Conditional – only for successful transaction in which a payment card was used
receipt	Details for the receipt.<br><br> For more information check 3.1.5.1 Receipt Format	Array	Conditional: <br><br>- always present for successful transactions <br><br>- always present if card was tapped
paymentSolutionReference	Transaction specific and unique identification (format: UUID)	String (UUID)	Conditional <br><br>- always present for successful transactions<br><br>- optional for failed transactions
reference	Reference (external transaction id) - set based on the value of the field with the same name sent in the request	String	Optional - presented if provided in the request
merchantIdentifier	Merchant unique identifier (MID)	String	Mandatory
terminalIdentifier	Terminal unique identifier (MID)	String	Mandatory
tipAmount	The tip amount added to authorisation amount as minor unit. This amount has the same currency as the transaction amount. The fraction is taken from the currency code.	Integer	Conditional - in case of tip is active and entered by the cardholder during transaction processing or provided in the request
dccOffered	True - in case of DCC is active and DCC selection was shown towards the cardholder	Boolean	Conditional - in case of DCC is active and DCC selection was shown towards the cardholder
dccUsed	True - in case of DCC was selected by the cardholder	Boolean	Conditional - in case of DCC was selected by the cardholder
dccAmount	Cardholder amount (Amount in cardholder currency	Integer	Conditional - in case of DCC is active and the cardholder has selected his own currency
dccCurrency	Cardholder currency	String	Conditional - in case of DCC is active and the cardholder has selected his own currency
dccExchangeRate	Used exchange rate	String	Conditional - in case of DCC is active and the cardholder has selected his own currency
cardholderVerificationMethod	Cardholder verification method<br><br> For more information check Appendix C.2 Cardholder Verification Method	String Conditional - in case of successful transaction
cardDataInput	The card data input method:<br><br>- WPI_CARD_DATA_INPUT_PROXIMITY_ICC - for card transactions<br><br>- WPI_CARD_DATA_INPUT_ALTERNATIVE_PAYMENT_METHOD - for BLIK and APM transactions	String	Conditional - in case of successful transaction
onBehalf	Inform if transaction was made on behalf of partner merchant – on partner terminal	Boolean	Conditional - mandatory for transaction performed on-behalf
terminalIdentifierLong	Terminal identifier built as (Platform Identifier)-(Merchant Identifier)-(Platform Terminal identifier)	String	Mandatory

Refund and Credit

The Service Type WPI_SVC_REFUND can be use to perform following transactions.

• Refund of existing transaction<br> Refunds are issued to the customer's card (a card tap is required) for an amount equal to or less than the original transaction amount. APM/Blik transactions are an exception, as the refund is always issued for the full amount of the original transaction. At least the currency, requested amount and payment solution reference (for refunding a card transaction) are needed for a refund.
• Credit custromer<br> For credit at minimum the currency, requestedAmount.

Prerequisites:

• ToM application correctly installed.
• Terminal properly registered (paired with the ToM backend system).
• Transaction parameters (currency, etc.) must be in accordance with the terminal profile.

WPI_REQUEST - list of supported input parameters

Field name	Description	Type	Condition
currency	Currency of the amount. Alpha code value defined in ISO 4217 (e.g. EUR)	String	Mandatory
requestedAmount	Total refund amount as minor unit. The fractional digits are evaluated based in the currency. For example, 11.91€ must be sent as 1191 and the currency as EUR. <br><br>Must be equal to or less than the original transaction amount.	Integer	Optional - mandatory for credit and card transaction refund
paymentSolutionReference	The UUID of the transaction for which the refund will be executed.	String(UUID)	Optional - mandatory for refund
reference	Reference (external transaction id) to be send to the payment solution for reconciliation<br><br>Due to the limitation of acquiring systems, only following characters are supported: ('a'..'z', 'A'..'Z', '0'..'9', hex 40 - hex FF) <br><br>max. length of this field is 30 characters	String	Optional
receiptFormat	Transaction confirmation format. The possible options are a set of data in JSON format to build the confirmation, a text-based confirmation, or displaying the transaction confirmation in the application.<br><br> For more information check 3.1.5.1 Receipt Format	Array	Optional
onBehalf	Multi-merchant mode - on behalf transaction flag<br><br> For more information check 3.1.5.2 Transactions on Behalf	Boolean	Optional – required when transaction should be performed ‘on behalf’ in multi-merchant mode.
partnerTid	Multi-merchant mode - partner terminal TID<br><br> For more information check 3.1.5.2 Transactions on Behalf	String	Conditional
partnerMid	Multi-merchant mode - partner terminal MID<br><br> For more information check 3.1.5.2 Transactions on Behalf	String	Conditional
partnerTerminalUuid	Multi-merchant mode - partner terminal UUID<br><br> For more information check 3.1.5.2 Transactions on Behalf	String (UUID)	Conditional
partnerTerminalExtId	Multi-merchant mode - partner terminal external Id<br><br> For more information check 3.1.5.2 Transactions on Behalf	String	Conditional
checkoutId	Checkout identifier<br><br> For more information check 3.1.5.4 Checkouts	String (UUID)	Optional – required when merchant operates under acquirer configured with checkout verification.

WPI_RESPONSE - list of supported output parameters

Field name	Description	Type	Condition
result	Result of the transaction:<br><br>- WPI_RESULT_SUCCESS In case of successful transaction<br><br>- WPI_RESULT_FAILURE In case of failed transaction<br><br>	String	Mandatory
errorCondition	Specific error reason <br><br> For more information check 3.3 Error codes and proper error handling	String	Mandatory
remark	Terminal / transaction specific message for detailed error descriptions. Text provided by payment app.	String	Conditional – only for NOT successful transaction
actionCode	Specific action to be performed by the business application(always returned WPI_ACTION_CODE_NONE)	String	Conditional – only for successful transaction
timestamp	Date and time of the transaction, indicated by the acquirer. <br><br> Format according to ISO 8601	String (ISO 8601)	Conditional – only for successful transaction
currency	Currency code of the transaction. Alpha code value defined in ISO 4217 e.g. EUR	String	Conditional – only for successful transaction
authorizedAmount	Amount of the transaction. The fraction is taken from the currency code. <br><br>Example: <br>Currency = EUR <br>requestedAmount = 3190<br>=> 31,90 €	Integer	Conditional – only for successful transaction
brandName	Brand name of used payment method <br><br> For more information check Appendix C.1 Brand Name	String	Conditional – only for successful transaction
customerLanguage	The merchant’s default language (set in the merchant’s data)<br><br>Format according to ISO 630-1 (alpha-2 code)	String	Conditional – only for successful transaction
applicationIdentifier	Payment card application identifier dependent on the used card e.g. for MasterCard A00000041010	String	Conditional – only for successful transaction in which a payment card was used
applicationLabel	Payment card application label, depending on the used card e.g. MasterCard DEBIT	String	Conditional – only for successful transaction in which a payment card was used
receipt	Details for the receipt.<br><br> For more information check 3.1.5.1 Receipt Format	Array	Conditional: <br><br>- always present for successful transactions <br><br>- always present if card was tapped
paymentSolutionReference	Transaction specific and unique identification (format: UUID)	String (UUID)	Conditional <br><br>- always present for successful transactions<br><br>- optional for failed transactions
reference	Reference (external transaction id) - set based on the value of the field with the same name sent in the request	String	Optional - presented if provided in the request
merchantIdentifier	Merchant unique identifier (MID)	String	Mandatory
terminalIdentifier	Terminal unique identifier (MID)	String	Mandatory
dccOffered	True - in case of DCC is active and DCC selection was shown towards the cardholder	Boolean	Conditional - in case of DCC is active and DCC selection was shown towards the cardholder
dccUsed	True - in case of DCC was selected by the cardholder	Boolean	Conditional - in case of DCC was selected by the cardholder
dccAmount	Cardholder amount (Amount in cardholder currency)	Integer	Conditional - in case of DCC is active and the cardholder has selected his own currency
dccCurrency	Cardholder currency	String	Conditional - in case of DCC is active and the cardholder has selected his own currency
dccExchangeRate	Used exchange rate	String	Conditional - in case of DCC is active and the cardholder has selected his own currency
cardholderVerificationMethod	Cardholder verification method<br><br> For more information check Appendix C.2 Cardholder Verification Method	String Conditional - in case of successful transaction
cardDataInput	The card data input method:<br><br>- WPI_CARD_DATA_INPUT_PROXIMITY_ICC - for card transactions<br><br>- WPI_CARD_DATA_INPUT_ALTERNATIVE_PAYMENT_METHOD - for BLIK and APM transactions	String	Conditional - in case of successful transaction
onBehalf	Inform if transaction was made on behalf of partner merchant – on partner terminal	Boolean	Conditional - mandatory for transaction performed on-behalf
terminalIdentifierLong	Terminal identifier build as (Platform Identifier)-(Merchant Identifier)-(Platform Terminal identifier)	String	Mandatory

Refund and Credit

The Service Type WPI_SVC_REFUND can be use to perform following transactions.

• Refund of existing transaction<br> Refunds are issued to the customer's card (a card tap is required) for an amount equal to or less than the original transaction amount. APM/Blik transactions are an exception, as the refund is always issued for the full amount of the original transaction. At least the currency, requested amount and payment solution reference (for refunding a card transaction) are needed for a refund.
• Credit custromer<br> For credit at minimum the currency, requestedAmount.

Prerequisites:

• ToM application correctly installed.
• Terminal properly registered (paired with the ToM backend system).
• Transaction parameters (currency, etc.) must be in accordance with the terminal profile.

WPI_REQUEST - list of supported input parameters

Field name	Description	Type	Condition
currency	Currency of the amount. Alpha code value defined in ISO 4217 (e.g. EUR)	String	Mandatory
requestedAmount	Total refund amount as minor unit. The fractional digits are evaluated based in the currency. For example, 11.91€ must be sent as 1191 and the currency as EUR. <br><br>Must be equal to or less than the original transaction amount.	Integer	Optional - mandatory for credit and card transaction refund
paymentSolutionReference	The UUID of the transaction for which the refund will be executed.	String(UUID)	Optional - mandatory for refund
reference	Reference (external transaction id) to be send to the payment solution for reconciliation<br><br>Due to the limitation of acquiring systems, only following characters are supported: ('a'..'z', 'A'..'Z', '0'..'9', hex 40 - hex FF) <br><br>max. length of this field is 30 characters	String	Optional
receiptFormat	Transaction confirmation format. The possible options are a set of data in JSON format to build the confirmation, a text-based confirmation, or displaying the transaction confirmation in the application.<br><br> For more information check 3.1.5.1 Receipt Format	Array	Optional
onBehalf	Multi-merchant mode - on behalf transaction flag<br><br> For more information check 3.1.5.2 Transactions on Behalf	Boolean	Optional – required when transaction should be performed ‘on behalf’ in multi-merchant mode.
partnerTid	Multi-merchant mode - partner terminal TID<br><br> For more information check 3.1.5.2 Transactions on Behalf	String	Conditional
partnerMid	Multi-merchant mode - partner terminal MID<br><br> For more information check 3.1.5.2 Transactions on Behalf	String	Conditional
partnerTerminalUuid	Multi-merchant mode - partner terminal UUID<br><br> For more information check 3.1.5.2 Transactions on Behalf	String (UUID)	Conditional
partnerTerminalExtId	Multi-merchant mode - partner terminal external Id<br><br> For more information check 3.1.5.2 Transactions on Behalf	String	Conditional
checkoutId	Checkout identifier<br><br> For more information check 3.1.5.4 Checkouts	String (UUID)	Optional – required when merchant operates under acquirer configured with checkout verification.

WPI_RESPONSE - list of supported output parameters

Field name	Description	Type	Condition
result	Result of the transaction:<br><br>- WPI_RESULT_SUCCESS In case of successful transaction<br><br>- WPI_RESULT_FAILURE In case of failed transaction<br><br>	String	Mandatory
errorCondition	Specific error reason <br><br> For more information check 3.3 Error codes and proper error handling	String	Mandatory
remark	Terminal / transaction specific message for detailed error descriptions. Text provided by payment app.	String	Conditional – only for NOT successful transaction
actionCode	Specific action to be performed by the business application(always returned WPI_ACTION_CODE_NONE)	String	Conditional – only for successful transaction
timestamp	Date and time of the transaction, indicated by the acquirer. <br><br> Format according to ISO 8601	String (ISO 8601)	Conditional – only for successful transaction
currency	Currency code of the transaction. Alpha code value defined in ISO 4217 e.g. EUR	String	Conditional – only for successful transaction
authorizedAmount	Amount of the transaction. The fraction is taken from the currency code. <br><br>Example: <br>Currency = EUR <br>requestedAmount = 3190<br>=> 31,90 €	Integer	Conditional – only for successful transaction
brandName	Brand name of used payment method <br><br> For more information check Appendix C.1 Brand Name	String	Conditional – only for successful transaction
customerLanguage	The merchant’s default language (set in the merchant’s data)<br><br>Format according to ISO 630-1 (alpha-2 code)	String	Conditional – only for successful transaction
applicationIdentifier	Payment card application identifier dependent on the used card e.g. for MasterCard A00000041010	String	Conditional – only for successful transaction in which a payment card was used
applicationLabel	Payment card application label, depending on the used card e.g. MasterCard DEBIT	String	Conditional – only for successful transaction in which a payment card was used
receipt	Details for the receipt.<br><br> For more information check 3.1.5.1 Receipt Format	Array	Conditional: <br><br>- always present for successful transactions <br><br>- always present if card was tapped
paymentSolutionReference	Transaction specific and unique identification (format: UUID)	String (UUID)	Conditional <br><br>- always present for successful transactions<br><br>- optional for failed transactions
reference	Reference (external transaction id) - set based on the value of the field with the same name sent in the request	String	Optional - presented if provided in the request
merchantIdentifier	Merchant unique identifier (MID)	String	Mandatory
terminalIdentifier	Terminal unique identifier (MID)	String	Mandatory
dccOffered	True - in case of DCC is active and DCC selection was shown towards the cardholder	Boolean	Conditional - in case of DCC is active and DCC selection was shown towards the cardholder
dccUsed	True - in case of DCC was selected by the cardholder	Boolean	Conditional - in case of DCC was selected by the cardholder
dccAmount	Cardholder amount (Amount in cardholder currency)	Integer	Conditional - in case of DCC is active and the cardholder has selected his own currency
dccCurrency	Cardholder currency	String	Conditional - in case of DCC is active and the cardholder has selected his own currency
dccExchangeRate	Used exchange rate	String	Conditional - in case of DCC is active and the cardholder has selected his own currency
cardholderVerificationMethod	Cardholder verification method<br><br> For more information check Appendix C.2 Cardholder Verification Method	String Conditional - in case of successful transaction
cardDataInput	The card data input method:<br><br>- WPI_CARD_DATA_INPUT_PROXIMITY_ICC - for card transactions<br><br>- WPI_CARD_DATA_INPUT_ALTERNATIVE_PAYMENT_METHOD - for BLIK and APM transactions	String	Conditional - in case of successful transaction
onBehalf	Inform if transaction was made on behalf of partner merchant – on partner terminal	Boolean	Conditional - mandatory for transaction performed on-behalf
terminalIdentifierLong	Terminal identifier build as (Platform Identifier)-(Merchant Identifier)-(Platform Terminal identifier)	String	Mandatory

Reversal

A reversal can be performed using the WPI_SVC_CANCEL_PAYMENT function.

A reversal is a technical operation that cancels a previously completed card transaction. Depending on the configuration, it is possible to cancel only the last transaction (default configuration) or all transactions performed on the given day. If a reversal cannot be executed, a refund should be used instead.

Important: for BLIK/APM transactions, a reversal is not available; in such cases, only a full refund of the transaction amount can be performed.

Prerequisites:

• ToM application correctly installed.
• Terminal properly registered (paired with the ToM backend system).
• Transaction parameters (currency, etc.) must be in accordance with the terminal profile.

WPI_REQUEST - list of supported input parameters

In WPI_SVC_CANCEL_PAYMENT at minimum the paymentSolutionReference (UUID of reversed transaction) is needed.

Field name	Description	Type	Condition
paymentSolutionReference	The UUID of the transaction for which the reversal will be executed.	String(UUID)	Mandatory

WPI_RESPONSE - list of supported output parameters

Field name	Description	Type	Condition
result	Result of the transaction:<br><br>- WPI_RESULT_SUCCESS In case of successful transaction<br><br>- WPI_RESULT_FAILURE In case of failed transaction<br><br>	String	Mandatory
errorCondition	Specific error reason <br><br> For more information check 3.3 Error codes and proper error handling	String	Mandatory
remark	Terminal / transaction specific message for detailed error descriptions. Text provided by payment app	String	Conditional – only for NOT successful transaction
actionCode	Specific action to be performed by the business application (always returned WPI_ACTION_CODE_NONE)	String	Conditional – only for successful transaction
merchantIdentifier	Merchant unique identifier (MID)	String	Mandatory
terminalIdentifier	Terminal unique identifier (MID)	String	Mandatory
terminalIdentifierLong	Terminal identifier build as (Platform Identifier)-(Merchant Identifier)-(Platform Terminal identifier)	String	Mandatory

Receipt Format

Tap on Mobile provides three options for transaction confirmation.

1. A text-based confirmation returned in the intent response.
2. A complete set of data required to build the confirmation independently, provided as JSON returned in the intent response.
3. A confirmation displayed in Tap on Mobile before exiting the intent.

The type of notification depends on the receiptFormat parameter sent in the WPI_REQUEST. The following combinations are possible:

• json"receiptFormat": ["FORMATTED"] <br>A text-formatted confirmation is returned in the response; the confirmation is not displayed in Tap on Mobile. <br>This is the default option, used when receiptFormat is not sent.<br><br>
• "receiptFormat": ["JSON"] <br>A set of data for building the confirmation is returned in the response; the confirmation is not displayed in Tap on Mobile.<br><br>
• "receiptFormat": ["JSON", "FORMATTED"] <br>Both a set of data for building the confirmation and a text-formatted confirmation are returned in the response; the confirmation is not displayed in Tap on Mobile.<br><br>
• "receiptFormat": [] <br>The confirmation is not displayed in Tap on Mobile and is not returned in the response.

A text-based confirmation returned

For "receiptFormat": ["FORMATTED"], the following structure is included in the response.

"receipt": \{
        "formatted": \{
            "client": "This is to confirm your transaction     \n registered at:                          \n ----------------------------------------\n APM TEST & Merchant                     \n APM street 1                            \n APM city 1234                           \n ----------------------------------------\n 05.12.2025 14:23:06                     \n VISA       **** **** **** 0013          \n Amount:                       PLN 110,00\n Tip Amount:                    PLN 12,10\n Total Amount:                 PLN 122,10\n Exchange rate:       PLN 1,00 - EUR 0,24\n DCC amount:                    EUR 29,30\n Markup incl.:                    21,00 %\n I have been offered a choice of         \n currencies and I accept the final       \n amount in transaction currency.         \n Currency conversion provided by         \n Worldline.                              \n Transaction details:                    \n Status:                          CLEARED\n Authorization code:           (00)000671\n ARQC:                   745CF00E167FA050\n AID:                      A0000000031010\n Contactless                             \n Card expiry date:                   2912\n Type:                               SALE\n POS ID:                         WLIN0006\n MID:                           102003271\n Reference:                   sprawdzMnie\n VISA\n ",
            "merchant": "This is to confirm your transaction     \n registered at:                          \n ----------------------------------------\n APM TEST & Merchant                     \n APM street 1                            \n APM city 1234                           \n ----------------------------------------\n 05.12.2025 14:23:06                     \n VISA       **** **** **** 0013          \n Amount:                       PLN 110,00\n Tip Amount:                    PLN 12,10\n Total Amount:                 PLN 122,10\n Exchange rate:       PLN 1,00 - EUR 0,24\n DCC amount:                    EUR 29,30\n Markup incl.:                    21,00 %\n I have been offered a choice of         \n currencies and I accept the final       \n amount in transaction currency.         \n Currency conversion provided by         \n Worldline.                              \n Transaction details:                    \n Status:                          CLEARED\n Authorization code:           (00)000671\n ARQC:                   745CF00E167FA050\n AID:                      A0000000031010\n Contactless                             \n Card expiry date:                   2912\n Type:                               SALE\n POS ID:                         WLIN0006\n MID:                           102003271\n Reference:                   sprawdzMnie\n VISA\n "
        }
}

In the client and merchant tags, the text confirmation intended respectively for the customer and the merchant is returned. The newline character \n is used to indicate line breaks in the text.

A complete set of data required to build the confirmation

For "receiptFormat": ["FORMATTED"], the following structure is included in the response.

"receipt": \{
"json": \{
            "acquirerIdentifier": "14008500000F",
            "additionalData": \{
                "transactionType": "AUTH",
                "transactionStatus": "CLEARED",
                "applicationCryptogram": "745CF00E167FA050",
                "cid": "ARQC"
            },
            "amount": 12210,
            "applicationIdentifier": "A0000000031010",
            "authorizationCode": "00 000671",
            "brandName": "WPI_BRAND_NAME_VISA",
            "cardDataInput": "WPI_CARD_DATA_INPUT_PROXIMITY_ICC",
            "cardExpiration": "2912",
            "cardholderVerificationMethod": "WPI_CVM_PIN_ONLINE",
            "currency": "PLN",
            "dccInfo": \{
                "dccAmount": 2930,
                "dccCurrency": "EUR",
                "dccDisclaimer": "I have been offered a choice of currencies and I accept the final amount in transaction currency. Currency conversion provided by Worldline.",
                "dccEcbIndicator": false,
                "dccExchangeRate": "0,24000",
                "dccMarkup": "21,00 %"
            },
            "duplicate": false,
            "legalIdentificationRequired": false,
            "maskedPan": "**** **** **** 0013",
            "operatorIdentifier": "102003271",
            "paymentSolutionReference": "ee002b63-09fe-4dcb-9681-5796607fd3c2",
            "receiptTargets": \{
                "client": \{
                    "description": "List of field names of the receipt to be included for the client receipt",
                    "items": [
                        "shopInfo",
                        "timestamp",
                        "brandName",
                        "maskedPan",
                        "currency",
                        "amount",
                        "tipAmount",
                        "dcc",
                        "transactionStatus",
                        "authorizationCode",
                        "applicationCryptogram",
                        "applicationIdentifier",
                        "transactionType",
                        "terminalIdentifier",
                        "operatorIdentifier",
                        "reference",
                        "cardExpiration"
                    ]
                },
                "merchant": \{
                    "description": "List of field names of the receipt to be included for the merchant receipt",
                    "items": [
                        "shopInfo",
                        "timestamp",
                        "brandName",
                        "maskedPan",
                        "currency",
                        "amount",
                        "tipAmount",
                        "dcc",
                        "transactionStatus",
                        "authorizationCode",
                        "applicationCryptogram",
                        "applicationIdentifier",
                        "transactionType",
                        "terminalIdentifier",
                        "operatorIdentifier",
                        "reference",
                        "cardExpiration"
                    ]
                }
            },
            "reference": "sprawdzMnie",
            "shopInfo": \{
                "address": "APM street 1, APM city 1234",
                "name": "APM TEST & Merchant"
            },
            "terminalIdentifier": "WLIN0006",
            "timestamp": "2025-12-05T14:23:06+01:00",
            "tipAmount": 1210
        }
}

A confirmation displayed in Tap on Mobile

For "receiptFormat": [], the transaction flow ends with the screen below.

The user has the option to either send the confirmation via email in PDF format (1) or display a QR code that allows downloading the PDF confirmation (2).

Transactions on Behalf

Multimerchant functionality allows selected terminals to perform transactions on behalf of other merchants/terminals.

The functionality can be enabled by an Administrator for selected clients. In this case, a merchant can be associated with two types of terminals:

• Primary terminal — it is linked to a specific device during the registration process and can be paired with partner terminals of other merchants; transactions can be performed both on its own behalf and on behalf of a selected partner terminal.
• Partner terminal — the application cannot be registered on it; partner transactions can be performed on its behalf.

A transaction performed on behalf of another terminal:

• has the on_behalf flag set to true.
• has the partner_tid and partner_mid fields populated — they contain the data of the partner terminal on whose behalf the transaction was performed.

Important: Refund and reversal of the on behalf transaction should be also performed on behalf the same terminal.

To perform an on-behalf transaction using WPI, the WPI_REQUEST must include onBehalf set to true and one of the following four fields:

• partnerTid Partner terminal TID
• partnerMid Partner terminal MID (The reference must be unique — it must point to exactly one paired terminal.)
• partnerTerminalUuid Partner terminal UUID
• partnerTerminalExtId Partner terminal external Id (The reference must be unique — it must point to exactly one paired terminal.)

An example of the minimal set of parameters required to perform an on-behalf transaction:

\{
    "currency": "EUR",
    "requestedAmount": 1500,
    "onBehalf": true,
    "partnerTid": "WLTP0009"
}

Tipping

Tap on Mobile allows adding a tip to a transaction. This functionality can be enabled by an Administrator for selected clients.

If tips are enabled for a terminal, two scenarios are possible:

• In the WPI_REQUEST, an additional tipAmount tag can be sent — it should contain the tip value. In this case, the tip will be added, and the authorization will be performed for the total amount: amount + tipAmount.
• If tips are enabled for the terminal but no tipAmount is provided in the WPI_REQUEST, the transaction flow will start with an additional screen where the user can decide whether to add a tip and specify the tip amount.

Note: If tips are disabled for the terminal but a tipAmount value is sent in the WPI_REQUEST, the transaction will end with an error:

\{
    "errorCondition": "WPI_ERR_COND_TIP_NOT_SUPPORTED_BY_PAYMENT_SOLUTION",
    "remark": "Terminal does not support tip.",
    "result": "WPI_RESULT_FAILURE",
    (...)
}

Checkouts

For acquirers having ‘checkout id’ verification enabled, verification of checkout is mandatory during transaction initialization.

ToM backoffice API has dedicated endpoint /api/v1/transaction-checkouts for checkout creation and getting checkout data so integrator could create checkouts. When creating a checkout_id, the following data can be provided:

Name	Description
id_merchant	Id of merchant	Mndatory
id_terminal	Id of terminal	Optional
amount	Transaction amount ‘in cents’ (no decimal numbers)	Optional
currency_alpha_code	Transaction currency code (alpha 3)	Optional
country_alpha_code2	Terminal country code (alpha 2)	Optional
external_id	External id of transaction	Optional

Later, during the transaction, each of the provided values is compared with the transaction data and must match.

API /api/v1/transaction-checkouts will create checkout_id ad return UUID of it. To perform transaction for acquirers having ‘checkout id’ verification enabled in WPI_REQUEST parameter checkoutId with this UUID must be added.

Information operations

Interface structure and activity launch

For informational purpose com.worldline.payment.action.PROCESS_INFORMATION intent should be used.

Type	Category	Intent	Purpose
Information	Background Actions : These actions perform background processing that usually does not require user interaction, but sometimes can require user interaction<br>Notice: Android intents are used	com.worldline.payment.action.PROCESS_INFORMATION	Background management of payment solution specific information

Here is intent creation code:

    public Intent formatInformationRequest(String sessionId, WpiPurchaseRequest req) \{
        String json = GSON.toJson(req);

        Intent intent = new Intent("com.worldline.payment.action.PROCESS_INFORMATION");
        intent.addFlags(Intent.FLAG_ACTIVITY_REORDER_TO_FRONT);
        intent.putExtra("WPI_SERVICE_TYPE", "WPI_SVC_LAST_TRANSACTION");
        intent.putExtra("WPI_REQUEST", json);
        intent.putExtra("WPI_VERSION", "2.2");
        intent.putExtra("WPI_SESSION_ID", sessionId);
        intent.putExtra("SHOW_OVERLAY ", false)

        return intent;
    }

Intent contains a set of extras and needs to have FLAG_ACTIVITY_REORDER_TO_FRONT set.

Extra	Descritpion	Type	Condition
WPI_SERVICE_TYPE	Specify the subtype of action to be executed. Currently supported one service type: WPI_SVC_LAST_TRANSACTION - function to recovery the result of the previous intent call	String	Mandatory
WPI_REQUEST	The request contains JSON structured data that is mandatory for the given service type.<br><br> For WPI_SVC_LAST_TRANSACTION empty JSON (\{}) should be sent.	String	Mandatory
WPI_VERSION	Used WPI version (current: 2.2)	String	Mandatory
WPI_SESSION_ID	For WPI_SVC_LAST_TRANSACTION seesion_id from previous intent request should be sent	String	Mandatory
SHOW_OVERLAY	The flag controls whether a transparent overlay (false) or a spinner (true) should be displayed at the start of the intent.	Boolean	Optional

To launch intent registerForActivityResult method should be used. In the response, the intent returns the following data.

Extra	Descritpion	Type	Condition
WPI_SERVICE_TYPE	Specify the subtype of action to be executed. For WPI_SVC_LAST_TRANSACTION this will be the service type of the recovered transaction not "WPI_SVC_LAST_TRANSACTION"	String	Mandatory
WPI_RESPONSE	The response contains JSON structured data from previous intent call (The Financial Payment Response object of the corresponding SESSION_ID)	String	Mandatory
WPI_VERSION	Used WPI version	String	Mandatory
WPI_SESSION_ID	Identifier of a WPI exchange, this session id will be the same as the one sent in the request	String	Mandatory

And here is response parsing sample code:

    public WpiPurchaseResponse parsePurchaseResponse(ActivityResult result) \{
        if (result.getResultCode() == Activity.RESULT_CANCELED) \{
            throw new RuntimeException("Intent cancelled.");
        }
        if (result.getResultCode() != Activity.RESULT_OK) \{
            throw new RuntimeException("Invalid result code: " + result.getResultCode());
        }

        Intent intent = result.getData();
        if (intent == null) \{
            throw new RuntimeException("Received intent without bundled data");
        }

        String json = intent.getStringExtra("WPI_RESPONSE");

        WpiPurchaseResponse resp = GSON.fromJson(json, WpiPurchaseResponse.class);
        resp.setSessionId(intent.getStringExtra("WPI_SESSION_ID"));

        return resp;
    }

Please remember
The important thing to note is that ToM can only handle one intent invocation at a time (of any intent type — it doesn’t matter whether it’s a financial or informational function). Therefore, it is crucial to make the next request only after receiving the response from the previous one.

Last transaction

In case of the last payment transaction response is not known any more it can be requested by this service. It will return the last financial transaction response independent of the result, failed or success. This is a recovery feature as the payment solution will remember the last SESSION_ID as well as corresponding transaction response. The Android Extras are close to a standard transaction response except for the conditional presence of WPI_SERVICE_TYPE & WPI_RESPONSE. An initial check on one of these extra properties can provide information about the existence of the session.

Be aware any payment solution will just store the last response. That implies that no other WPI request shall be done before the recovery.

For more information about proper error handling see 3.3 Error codes and proper error handling

WPI_REQUEST - list of supported input parameters

For WPI_SVC_LAST_TRANSACTION, an empty JSON must be sent in the WPI_REQUEST. The function does not expect any additional input parameters.

WPI_RESPONSE - list of supported output parameters

The structure of WPI_RESPONSE depends on the previously invoked function — the WPI_RESPONSE contains the response from the previously called intent.

Error codes and proper error handling

The list of potential errors that may be returned by WPI is presented in the table below.

Error condition	Description
WPI_ERR_COND_NONE	Transaction processed sucessfully without error.
WPI_ERR_COND_BUSY	Other intent request was during processing - in such situation both request (ongoing and new) will be finised. For ongoing error will be depend of curent status, for new request WPI_ERR_COND_BUSY wil be returned.
WPI_ERR_COND_CARD_READ_ERR	Card was refused durin reading (card is not supoorted or errors during card reading).
WPI_ERR_COND_GENERIC	NFC hardware not available/NFC hardware not available/ other technical error on device.
WPI_ERR_COND_HOST_REFUSAL	Transaction was refused by authorisation host or terminal is not properly registered and Tap on Mobile host refuse to proces transaction.
WPI_ERR_COND_INTERNAL	Application internal error\other unhandled errors.
WPI_ERR_COND_INVALID_AMOUNT	In request parameters entered invalid transaction amount, eg. 0.
WPI_ERR_COND_INVALID_CURRENCY	In request parameters entered invalid currency other then parametrised for terminal.
WPI_ERR_COND_INVALID_PASSWORD	Specific error — for this terminal, entering a PIN is required to perform a refund, and the user entered an incorrect PIN three times.
WPI_ERR_COND_INVALID_TRANSACTION_REQ	- Security errors during application start <br>- Checkout functionality specyfic errors - mising/wrong checkoutid <br>- refund or reversal of transaction was called but transaction does not exist, or can't be refunded/reversed.
WPI_ERR_COND_MISSING_MANDATORY_PARAMETER	One of thr mandatory parameter is missingi in WPI_REQUEST.
WPI_ERR_COND_NOT_INITIALIZED	The payment solution is not configured and cannot process the request.
WPI_ERR_COND_SERVICE_NOT_SUPPORTED	I/O errors, socket timeouts and other such technical problems.
WPI_ERR_COND_TIP_AMOUNT_EXCEEDS_MAXIMUM	Sended tipAmount is larger then limits definied for terminal.
WPI_ERR_COND_TIP_NOT_SUPPORTED_BY_PAYMENT_SOLUTION	Tipping not allowed for terminal but tipAmount parameter was send in WPI_REQUEST.
WPI_ERR_COND_TIP_NOT_SUPPORTED_BY_SERVICE_TYPE	tipAmount is not supported in this WPI functions (eg reversal does not support it)
WPI_ERR_COND_TLP_NOT_FINALIZED	Estey and TLP specific error - The transaction can only be refunded to the same card.
WPI_ERR_COND_TRANSACTION_TIMEOUT	Timeout caused by the customer — the time expired for card reading, PIN entry, etc.
WPI_ERR_COND_USER_CANCEL	Transaction cancelled by user before authorisation.
WPI_ERR_COND_WPI_VERSION_NOT_SUPPORTED	- Wrong, not suported version of WPI<br>- Wrong ToM application version<br>- Atestation error.
WPI_ERR_TLP_NOT_FINALIZED	Estey and TLP specific error - terminal is managed by TLP but activation not completed. At this moment, transaction can be performed on this terminal.
WPI_ERR_UPDATE_REQUIRED	- A newer version of the transaction is available and the user interrupted the intent call to download it.<br> - An application update is required, but the user refused the update.

When handling errors, the following should be taken into account:

• In the event of a lost connection between the application and the backend during the transaction flow, there may be situations in which WPI returns an error, but the transaction is actually completed.
• The intent may return an empty response (for example, in the case of an application crash).

Therefore, for selected error types and in situations where an empty response is received, the LAST_TRANSACTION function should additionally be used to confirm the transaction result. The correct algorithm is shown in the diagram below.

Worldline Management Interface (WMI)

Interface structure and activity launch

The WPI provides a set of intents that developers can use to build apps that work with the interface.

For management purpose com.worldline.management.action.PROCESS_OPERATION intent should be used.

Type	Category	Intent	Purpose
Management	Display Action - these actions start the payment solution that are processing financial transactions or require user interaction.<br>Notice: Android intents are used	com.worldline.payment.action.PROCESS_OPERATION	Process a management request

Here is intent creation code:

    public Intent formatWmiRequest(String sessionId, WpiPurchaseRequest req) \{
        String json = GSON.toJson(req);

        Intent intent = new Intent("com.worldline.management.action.WMI_SVC_CHECK_STATUS");
        intent.addFlags(Intent.FLAG_ACTIVITY_REORDER_TO_FRONT);
        intent.putExtra("WMI_SERVICE_TYPE", "WPI_SVC_PAYMENT");
        intent.putExtra("WMI_REQUEST", json);
        intent.putExtra("SHOW_OVERLAY ", false)

        return intent;
    }

Intent contains a set of extras and needs to have FLAG_ACTIVITY_REORDER_TO_FRONT set.

Extra	Descritpion	Type	Condition
WMI_SERVICE_TYPE	Specify the subtype of action to be executed:<br>- WMI_SVC_CHECK_STATUS - Service type for checking current Tap on Mobile application status<br><br>- WMI_SVC_REGISTER - Service type for initiating the terminal enrollment sequence<br><br>- WMI_SVC_AUTH_UNREGISTER - Service type for unregistering the terminal by the 3rd party application package used previously for enrollment<br><br>	String	Mandatory
WMI_REQUEST	The request contains JSON structured data that is mandatory for the given service type.<br><br> The JSON structure is described in the following chapters for each function.	String	Mandatory
SHOW_OVERLAY	The flag controls whether a transparent overlay (false) or a spinner (true) should be displayed at the start of the intent.	Boolean	Optional

To launch intent registerForActivityResult method should be used. In the response, the intent returns the following data.

Extra	Descritpion	Type	Condition
WMI_SERVICE_TYPE	Specify the subtype of action to be executed	String	Mandatory
WMI_RESPONSE	The response contains JSON structured data processed for the requested service type	String	Mandatory

And here is response parsing sample code:

    public WmiPurchaseResponse parsePurchaseResponse(ActivityResult result) \{
        if (result.getResultCode() == Activity.RESULT_CANCELED) \{
            throw new RuntimeException("Intent cancelled.");
        }
        if (result.getResultCode() != Activity.RESULT_OK) \{
            throw new RuntimeException("Invalid result code: " + result.getResultCode());
        }

        Intent intent = result.getData();
        if (intent == null) \{
            throw new RuntimeException("Received intent without bundled data");
        }

        String json = intent.getStringExtra("WMI_RESPONSE");

        WmiPurchaseResponse resp = GSON.fromJson(json, WmiPurchaseResponse.class);


        return resp;
    }

Please remember
The important thing to note is that ToM can only handle one intent invocation at a time (of any intent type — it doesn’t matter whether it’s a financial or informational function). Therefore, it is crucial to make the next request only after receiving the response from the previous one.

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

WMI_REQUEST - list of supported input parameters

None – might be created for future use.

WMI_RESPONSE - list of supported output parameters

Field name	Description	Type	Condition
result	Result of the transaction:<br><br>- WPI_RESULT_SUCCESS In case of successful transaction<br><br>- WPI_RESULT_FAILURE In case of failed transaction<br><br>	String	Mandatory
errorCondition	Specific error reason <br><br> For more information check 4.5 Error codes and proper error handling	String	Mandatory
remark	Terminal / transaction specific message for detailed error descriptions. Text provided by payment app.	String	Conditional – only for NOT successful transaction
appStatus	Tap on Mobile application status indicating whether application is already registered.<br><br>For more information check Appendix C.3 Application statuses

Terminal registration

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_REQUEST - list of supported input parameters

Field name	Description	Type	Condition
registrationToken	TID specific registration token retrieved from Tap on Mobile backend (Merchant API); in case this parameter is not present, Tap on Mobile app will collect all required permissions and launch QR-code reader to scan the registration token;	String	Optional

WMI_RESPONSE - list of supported output parameters

Field name	Description	Type	Condition
result	Result of the transaction:<br><br>- WPI_RESULT_SUCCESS In case of successful transaction<br><br>- WPI_RESULT_FAILURE In case of failed transaction<br><br>	String	Mandatory
errorCondition	Specific error reason <br><br> For more information check 4.5 Error codes and proper error handling	String	Mandatory
remark	Terminal / transaction specific message for detailed error descriptions. Text provided by payment app.	String	Conditional – only for NOT successful transaction

Terminal unregistration

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.

WMI_REQUEST - list of supported input parameters

None – might be created for future use;

WMI_RESPONSE - list of supported output parameters

Field name	Description	Type	Condition
result	Result of the transaction:<br><br>- WPI_RESULT_SUCCESS In case of successful transaction<br><br>- WPI_RESULT_FAILURE In case of failed transaction<br><br>	String	Mandatory
errorCondition	Specific error reason <br><br> For more information check 4.5 Error codes and proper error handling	String	Mandatory
remark	Terminal / transaction specific message for detailed error descriptions. Text provided by payment app.	String	Conditional – only for NOT successful transaction

Error codes and proper error handling

Error condition	Description
WMI_ERR_COND_NONE	Will always be present if no error occurred, confirms successful result
WMI_ERR_COND_AUTH_NOT_POSSIBLE	Valid terminal registration was not found.
WMI_ERR_COND_GENERIC	A mobile application generic error that is not explicitly outlined here
WMI_ERR_COND_INTERNAL	Backend-driven generic error that is not explicitly outlined here
WMI_ERR_COND_INVALID_JSON	Wrong structure of WMI_REQUEST json
WMI_ERR_COND_NETWORK_ISSUE	Problems with network connection
WMI_ERR_COND_SERVICE_NOT_SUPPORTED	Requested service type is not supported by the Payment Application
WMI_ERR_COND_TERMINAL_BUSY	Terminal communication is exclusively restricted to another 3rd party application package
WMI_ERR_PERMISSION	To old version of Tap on Mobile application. Upgrade to newest is needed

Tap on Mobile backend API

Implementing the Tap on Mobile integrated authentication mode requires integrating the third-party application backend directly with the ToM backend API. Storing OAuth2 access credentials directly in the mobile application is 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.

ToM backend API OAuth2 authentication

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

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

Request Parameters

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

Parameter	Description	Type	Condition
grant_type	A string indicating which grant type is being used: client_credentials	String	Mandatory
scope	The scope of the access token, indicating the permissions that are granted to the client	String	Optional (depends on API)
client_id	A unique identifier for the client application, issued by the authorization server	String	Mandatory
client_secret	A secret string used to authenticate the client application with the authorization server	String	Mandatory

Response Parameters

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

Parameter	Description	Type	Condition
access_token	A string containing the access token, which will be used for the terminal authentication endpoint	String	Mandatory
scope	The scope of the access token, indicating the permissions that are granted to the client	String	Optional (depends on API)
token_type	The type of access token. For example “Bearer”	String	Mandatory
expires_in	The number of seconds before the access token expires and a new one must be requested	Integer	Mandatory

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

<img src="./img/midStructure.png" width="75%">

CONTRACT_ID is optional and only used in case lower level tiers require aggregation; VAT_ID is optional and only used in case lower level tiers require 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.

Request Parameters

Complete list of function request elements is available in ToM API specification (https://sandbox-wl-emea.softpos.eu/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/Terminals/search_8). Tables below summarize most important parameters and function filters.

Parameter	Description	Type	Condition
page	Integer defining a zero-based page index (default is 0)	Integer	Optional
size	Integer defining number of items to be returned in a single page (default is 10)	Integer	Optional
sort	String defining response list sorting criteria in the format: property,(asc|desc). Default order is ascending. Multiple sort criteria are supported	String	Optional

Parameter	Description	Type	Condition
contract_id	Merchant tier level identifier or combination of identifiers defining which part of terminal structure should be returned	String	Optional
vat_id	Merchant tier level identifier or combination of identifiers defining which part of terminal structure should be returned	String	Optional
mid	Merchant tier level identifier or combination of identifiers defining which part of terminal structure should be returned	String	Optional
tid	Terminal identifier. Used when current terminal details need to be checked	String	Optional
connected	Terminal assignment status: true – terminal is linked to a device; false – terminal is unassigned and available	Boolean	Optional
disabled	Flag indicating whether the terminal is temporarily restricted from performing operations	Boolean	Optional

Response Parameters

Complete list of response elements is available in ToM API specification (https://sandbox-wl-emea.softpos.eu/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/Terminals/search_8). Table below summarizes most important fields.

Parameter	Description	Type	Condition
id	Terminal UUID stored in the ToM backend	String (UUID)	Mandatory
external_id	3rd party terminal identifier (if assigned and present)	String	Optional
tid	ToM backend recognized active TID selected for assignment	String	Mandatory
mid	ToM backend recognized MID corresponding to the selected TID	String	Mandatory

Locking a terminal selected for registration

The decision on the TID selected for registration should be followed by the generation of a registration token. 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}/registration-token, 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.

Request Parameters

Complete list of request elements is available in ToM API specification (https://sandbox-wl-emea.softpos.eu/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/Terminals%20Registrations/registrationToken). Table below summarizes most important fields.

Parameter	Description	Type	Condition
id	Terminal UUID stored in the ToM backend	String (UUID)	Mandatory

Parameter	Description	Type	Condition
email	Optional parameter allowing to provide an email address of the user who should receive a welcome email containing the registration token in QR-code format; an empty body should be used when no user notification is required	String	Optional

Response Parameters

Complete list of response elements is available in ToM API specification (https://sandbox-wl-emea.softpos.eu/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/Terminals%20Registrations/registrationToken). Table below summarizes most important fields.

Parameter	Description	Type	Condition
token	Generated registration token to be used in the Tap on Mobile application for registering the selected TID	String	Mandatory
expiry_date	Registration token expiry timestamp	String (timestamp)	Mandatory
created	Registration token creation timestamp	String (timestamp)	Mandatory

Appendix A - How to register application manually

For the terminal registration process, an interaction between the terminal operator and the online portal administrator is needed.

A detailed description of the app installation and registration process can be found in the document Worldline_Tap_on_Mobile_user_manual. The documentation should be shared with terminal operator in case he is involved in terminal registration / different from online portal administrator.

Terminal registration process - based on codes

1. Login to the online Portal and click on the ‘Terminals’ section. <br><br>
2. Select a Terminal with status ‘Available’ on click the arrow button to expand the terminal view. <br><br><br>Press Registration button to start the terminal registration. <br><br>
3. In mobile app choose Online terminal registration<br><br> Then enter the code of the Worldline Tap on Mobile app entered in the ‘Code’ field of the online Portal. Afterwards click Find registration <br><br>
4. Click Confirm registration <br><br>
5. The online Portal displays a verification code. Enter this code in the terminal app.<br><br>
6. Click the Close button in the online Portal at this stage. The terminal registration process in the online Portal is finished.
7. Please finalize the registration on the terminal to get ready to accept payments. Please refer to Worldline_Tap_on_Mobile_user_manual if guidance is needed.

Terminal registration process - based on qrcode

1. Login to the online Portal and click on the ‘Terminals’ section. <br><br>
2. Select a Terminal with status ‘Available’ on click the arrow button to expand the terminal view. <br><br><br>Press QR Registration button to start the terminal registration. <br><br>
3. In mobile app choose QR code<br><br> Then scan QR Code. <br>
4. Click the Close button in the online Portal at this stage. The terminal registration process in the online Portal is finished.
5. Please finalize the registration on the terminal to get ready to accept payments. Please refer to Worldline_Tap_on_Mobile_user_manual if guidance is needed.

Appendix B - Transaction Statuses

Status|Description|Integrator|Card|APM|Blik|

|----------|-----------|-----------|-----------|-----------|-----------| |NEW|Newly created payment.|Initial status. If a transaction has this status after the intent is completed (payment/refund), it will not be completed successfully. It will be automatically canceled after no more than several minutes.|X|X|X| |TIMEOUT|Transaction expired – timout on mobile app.|Transitional status. If a transaction has this status after the intent is completed (payment/refund), it will not be completed successfully. It will be automatically canceled after no more than several minutes.|X|X|| |DECLINED|Checkin declined by SATA or customer.|Final status. The transaction was rejected by the authorization host.|X|X|X| |TERMINAL_DECLINED|Declined by kernel.|Final status. Payment card read error.|X||| |CHECKINED|Checkin completed successfully.|Transitional status. If a transaction has this status after the intent is completed (payment/refund), it will not be completed successfully. It will be automatically canceled after no more than several minutes.||X|| |USER_CANCELLED|Transaction cancelled by the merchant or customer.|Final status. Transaction cancelled by user.|X|X|| |ONGOING|Authorization has been started, waiting for confirmation on customer mobile app.|Transitional status. If a transaction has this status after the intent is completed (payment/refund), it will not be completed successfully. It will be automatically canceled after no more than several minutes.|X|X|X| |PIN_REQUESTED|PIN requested by kernel.|Transitional status. If a transaction has this status after the intent is completed (payment/refund), it will not be completed successfully. It will be automatically canceled after no more than several minutes.|X||| |ACCEPTED|Payment accepted by the host, the status will change to CLEARED once the customer has been informed of the success of the transaction in the application. In all other cases, the status will be changed to CANCELLING.|Transitional status. If a transaction has this status after the intent is completed (payment/refund), it will not be completed successfully. It will be automatically canceled after no more than several minutes.||X|X| |CANCELLING|Transaction cancelled unsuccessfully, Scheduler is working in a loop. This status can be treated as CANCELLED.|Final status. The transaction should be treated as canceled.|X|X|X| |CLEARED|Payment completed.|Final status. Transaction successfuly authorised.|X|X|X| |CANCELLED|Previously authorized transaction reversed/cancelled by CANCEL_TRANSACTION due to various errors or unfinished transactions.|Final status. The transaction was canceled.|X|X|X| |CANCEL_FAILED|Transction not cancelled due to various errors or when number of Scheduler retries reaches retry limit. This status can be treated as CANCELLED.|Final status. The transaction should be treated as canceled.|X|X|| |REJECTED|Other interruptions.|Final status. The transaction ended with an error.|X||| |REFUNDED|Transaction refunded.|Final status. The transaction was refunded.|X|X|| |AUTHORIZED|Transaction authorized.|Final status. Transaction successfuly authorised.|X||| |ERROR|Transaction processing failed.|Final status. The transaction ended with an error.|X||| |DCC_REQUIRED|Customer is asked to accept/reject a DCC offer.|Transitional status. If a transaction has this status after the intent is completed (payment/refund), it will not be completed successfully. It will be automatically canceled after no more than several minutes.|X|||

Card payments

Transition matrix presenting the flow of the statuses while the card transactions are processed. This diagram shows all the possible transaction types and statuses.

<img src="./img/card.drawio.png" width="100%">

Excerpt of above diagram, presenting the flow of the statuses while the card sell transaction is processed.

<img src="./img/card_sell.drawio.png" width="100%">

Statuses flow for Card payment basing on application interface.

<img src="./img/card_flow.png" width="100%">

APM payments

Transition matrix presenting the flow of the statuses while the APM transactions are processed. This diagram shows all the possible transaction types and statuses.

<img src="./img/apm.drawio.png" width="100%">

Excerpt of above diagram presenting the flow of the statuses of failed APM transaction, caused by inactive host.

<img src="./img/apm_failed.drawio.png" width="100%">

Statuses flow for APM payment basing on application interface.

<img src="./img/apm_flow.png" width="100%">

BLIK payments

Transition matrix presenting the flow of the statuses while the Blik transactions are processed. This diagram shows all the possible transaction types and statuses.

<img src="./img/blik.drawio.png" width="100%">

Excerpt of above diagram presenting the flow of the statuses while the Blik sell transaction is processed.

<img src="./img/blik_sell.drawio.png" width="100%">

Statuses flow for BLIK payment basing on application interface.

<img src="./img/blik_flow.png" width="100%">

Appendix C

Brand Name

Brand Name
WPI_BRAND_NAME_ALIPAY
WPI_BRAND_NAME_AMERICAN_EXPRESS
WPI_BRAND_NAME_BANCONTACT
WPI_BRAND_NAME_BLIK
WPI_BRAND_NAME_CARTE_BANCAIRE
WPI_BRAND_NAME_CHINA_UNIONPAY
WPI_BRAND_NAME_DINERS_CLUB
WPI_BRAND_NAME_DISCOVER
WPI_BRAND_NAME_GIROCARD
WPI_BRAND_NAME_JCB
WPI_BRAND_NAME_LOCAL_CREDIT_CARD
WPI_BRAND_NAME_LOCAL_DEBIT_CARD
WPI_BRAND_NAME_LOCAL_QR_CODE_BRAND
WPI_BRAND_NAME_MAESTRO
WPI_BRAND_NAME_MASTERCARD
WPI_BRAND_NAME_MASTERCARD_DEBIT
WPI_BRAND_NAME_PAYCONIQ
WPI_BRAND_NAME_TWINT
WPI_BRAND_NAME_VISA
WPI_BRAND_NAME_VISA_DEBIT
WPI_BRAND_NAME_VISA_ELECTRON
WPI_BRAND_NAME_VPAY
WPI_BRAND_NAME_WECHAT_PAY
WPI_BRAND_NAME_OTHER

Cardholder Verification Method

Cardholder Verification Method
WPI_CVM_NO_CVM
WPI_CVM_PIN_ONLINE
WPI_CVM_SIGNATURE
WPI_CVM_CD_CVM

Application statuses

Status	Description
NEW	Technical status (should not be expected) indicating that registration process may be performed; Tap on Mobile application is not registered
INITIALIZED	Registration process may be performed; Tap on Mobile application is not registered
REGISTERED	Tap on Mobile application is registered but not yet authenticated – WPI functions may be performed;
AUTHENTICATED	Technical status (should not be expected) indicating that Tap on Mobile application still performs configuration activities
ACTIVE	Tap on Mobile application is authenticated and ready to perform payment acceptance functions (WPI);
ERROR	Tap on Mobile application crash

Appendix D - Testing procedure

Integration development is made on test environment. Test environment supports any cards for the following worldwide card brands:

• Visa
• V-Pay
• Mastercard
• Maestro
• American Express

It supports also local card brands:

• Eftpos – Australia
• Bancontact - Belgium

Alternative Payment Methods supported:

• based on QR Codes:<br>- Twint<br>- AliPay<br>- Payconiq
• Based on 1-time codes generated by banking app<br> - Blik

All cards can be used (including “the real” ones), but we suggest to use test cards provided in following test applications available at Google Play:

Application	Link	Cards included
Visa Mobile CDET	https://play.google.com/store/search?q=visa+cdet&c=apps&hl=pl&gl=US	- Visa
HCE Test Tool	https://play.google.com/store/apps/details?id=cz.pb.hce.test_tool.open&hl=pl&gl=US	- Visa<br>- Mastercard

It is possible to simulate special behavior / response code for the application by sending and special amount of 42.XX, where XX stands for the required ISO response code.

Transaction amount	Trasnaction Status	ISO response code	Descritpion
42.00	Accepted	00	Approved or completed successfully
42.04	Rejected	04	Retain Card
42.05	Rejected	05	Authorization declined
42.33	Rejected	33	Card expired
42.55	Rejected	55	Incorrect PIN
42.60	To be continued	60	SCA required – transaction to be continued
42.61	Rejected	61	Exceeds approval amount limit
42.xx	Rejected	xx	Any other response code

Tap on Mobile package names<br> There are separated apps dedicated for particular Worldline acquirers:

Acquirer	Android Package name	Region of availability
Worldline EU	eu.softpos.softposwrapper.wl	European Union
Worldline CH	eu.softpos.softposwrapper.wl	Switzerland
Worldline UK	eu.softpos.softposwrapper.wl	UK
Payone	eu.softpos.softposwrapper.payone	Austria; Germany
KB Smart	eu.softpos.softposwrapper.kb	Czechia
ANZ Worldline	eu.softpos.softposwrapper.wlanz	Australia

Appendix E - Network settings

Tap on Mobile application connects to various endpoints, depending on the acquirer.

Sandbox:

Acquirer	Endpoint name	Region of availability
Worldline EU	https://sandbox-wl-emea.softpos.eu	European Union
Worldline CH	https://sandbox-wl-ch.softpos.eu	Switzerland
Worldline UK	https://sandbox-wl-emea.softpos.eu	UK
Payone AT	https://sandbox-payone-at.softpos.eu	Austria
Payone DE	https://sandbox-payone-at.softpos.eu	Germany
KB Smart	https://sandbox-payphone-cz.softpos.eu	Czechia
ANZ Worldline	https://taponmobile.portal.sandbox.anzworldline-solutions.com.au	Australia

Production:

Acquirer	Endpoint name	Region of availability
Worldline EU	https://worldline.softpos.eu	European Union
Worldline CH	https://worldline.softpos.eu	Switzerland
Worldline UK	https://worldline.softpos.eu	UK
Payone AT	https://payone-at.softpos.eu	Austria
Payone DE	https://payone-at.softpos.eu	Germany
KB Smart	https://portal.payphone.cz	Czechia
ANZ Worldline	https://taponmobile.portal.anzworldline-solutions.com.au	Australia

Additional services:

Every Tap on Mobile requires also access to Google Services hosts:

• https://www.googleapis.com
• https://maps.googleapis.com