Worldline Payment Interface

Version 2.2.2

Introduction
Communication Layer
- Android Inter App Communication
Data Dictionary

1. Introduction

This page is intended for third-party application providers who want to develop business applications for Worldline Payment Applications. This document only covers use cases for the Worldline Tap on Mobile.

To interact with a payment application, Worldline has defined the Worldline Payment Interface, also known as WPI. WPI is designed 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 only displayed in the event of a transaction.

The transaction flow and screens cannot be changed due to the payment protocol and PCI requirements.

All source code examples are written in Kotlin (Android).

1.1 Supported Transaction Types

At this stage the following transaction types are supported:

Payment - Standard purchase transaction
Refund - Return funds for a previous transaction
Reversal/Cancellation - Cancel the last successful purchase

A Reversal transaction can only be used for the last successful purchase transactions (Payment). A Refund transaction can only be used for successful purchase transactions (Payment) that cannot be Reversed/Cancelled.

1.2 Preconditions

Before you can start the implementation, you must meet the following preconditions:

Development Environment

Development IDE for Android development with Android Toolkit

Sandbox App

Worldline Tap on Mobile Sandbox App installed

Application Project

Fully available Android application project

Whitelist

Your package name has to be whitelisted for Tap on Mobile app

1.3 Versioning

Every WPI version Y.X is backward compatible with all Y versions. A payment solution who has implemented version 1.1 can be used with request in version 1 (1.0) format. A Version 2.2 cannot be used with a request with version 1.1.

Tap on Mobile Support Matrix:

ID	Tap on Mobile Version	WPI 1.0	WPI 2.0	WPI 2.1	WPI 2.2
1	2.1.25	Ok	N/A	-	-
2	2.1.25.1	Ok	N/A	-	-
3	2.1.28	Ok	N/A	-	-
4	2.1.28.1	Ok	N/A	-	-
5	2.1.29	Ok	N/A	-	-
6	2.1.30	Ok	N/A	Ok	-
7	2.1.31	Ok	N/A	Ok	-
8	2.1.32.X	Ok	N/A	Ok	-
9	2.1.34.X	Ok	N/A	Ok	-
10	4.1.39.x	Ok	N/A	Ok	Ok
11	5.3.0	Ok	N/A	Ok	Ok
12	5.4.0	Ok	N/A	Ok	Ok

2. Communication Layer

2.1 Android Inter App Communication

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

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

Explicit Intents: These intents are used to launch a specific component within the same app. The target component is specified explicitly in the intent.
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. WPI 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.

2.1.1 Interface Structure

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

Type	Category	Intent	Purpose
Financial	Display Action	`com.worldline.payment.action.PROCESS_TRANSACTION`	Process a financial transaction
Information	Background action	`com.worldline.payment.action.PROCESS_INFORMATION`	Background management of payment solution specific information

We have two categories for the Interface:

Display Actions: These actions start the payment solution that are processing financial transactions or require user interaction (Android intents are used)
Background Actions: These actions perform background processing that doesn't require user interaction, but sometimes can require user interaction (due to COTS device specification)

2.1.2 Android Intent Implementation

The start of a payment is based on an intent. Each special transaction type has a set of parameters that are mandatory. To test transactions, you can use the Worldline Tap on Mobile Test App.

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

Request Extras:

Extra	Description	Type	Condition
`WPI_SERVICE_TYPE`	Specify the subtype of action to be executed	String	Mandatory
`WPI_REQUEST`	The request contains JSON structured data mandatory for given service type	String	Mandatory
`WPI_VERSION`	Used WPI version	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.	String	Mandatory

The session id: * Must be unique * Must be part of the response * Must not be reused for subsequent requests In the case of an unexpected failure during an exchange, the session id can be used in order for the client to restore its state and sync the exchange status with the payment application.

Response Extras:

Extra	Description	Type	Condition
`WPI_SERVICE_TYPE`	Specify the subtype of action to be executed	String	Mandatory
`WPI_RESPONSE`	The response contains JSON structure 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

Complete Implementation Example:

/**
 * Code snippet only
 * SaleTransactionRequest and SaleTransactionResponse are not provided - they are simple POJOs
 */
class SaleActivity : AppCompatActivity() {
    val launcher = registerForActivityResult(
        ActivityResultContracts.StartActivityForResult()
    ) { result ->
        result.data?.let { handleTransactionResponse(it) }
    }

    private fun startTransactionIntent(transactionJson: String, serviceType: String) {
        val intent = Intent("com.worldline.payment.action.PROCESS_TRANSACTION")
        // These extras are mandatory whether the intent comes from the payment
        // application or a 3rd party application.
        intent.putExtra("WPI_SERVICE_TYPE", serviceType)
        intent.putExtra("WPI_REQUEST", transactionJson)
        intent.putExtra("WPI_VERSION", "2.2")
        intent.putExtra("WPI_SESSION_ID", currentSession)

        launcher.launch(intent)
    }

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

**Important Considerations:** * It is strictly advised to store `WPI_SESSION_ID` within the business application * No new transaction should be initiated before the result of the previous is known * If the previous transaction status is unknown to the cash register, last transaction should be used to get it from Tap on Mobile app

3. Data Dictionary

This chapter describes the data exchange format. All requests and responses use JSON as data exchange format.

3.1 Service Type

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

3.2 Transaction Data

3.2.1 Purchase

The Service Type for a purchase transaction is WPI_SVC_PAYMENT. At minimum the currency and requestedAmount is needed.

Field Name	Description	Type	Condition
`currency`	Currency of the amount. Alpha code value defined in ISO 4217 (e.g. EUR)	String	Mandatory
`requestedAmount`	Total payment amount as minor unit. The fractional digits are evaluated based on the currency. For example, 11.91EUR must be sent as 1191 and the currency as EUR. (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.	Integer	Optional
`reference`	Reference to be sent to the payment solution for reconciliation	String	Optional
`receiptFormat`	Receipt format preference	Array	Optional

Due to the limitation of acquiring systems, only following characters are supported in the reference field: `('a'..'z', 'A'..'Z', '0'..'9', hex 40 - hex FF)`

Example Request:

{
  "currency": "EUR",
  "requestedAmount": 1022,
  "reference": "myRef_01"
}

TIP Handling

TIP functionality has to be enabled in Tap on Mobile portal on every terminal by checking the field "TIP Enabled"
If tipAmount in the WPI request is not defined and TIP is enabled: Tap on Mobile app will show the tip entry screens
If tipAmount in the WPI request is defined > 0 and TIP is enabled: Tap on Mobile will take the tip amount from the request and not show the tip entry screen
If tipAmount is null or 0: ToM will not show the tip entry screen and no tip will be processed as part of given transaction

3.2.2 Reversal/Cancellation

The Service Type for a reversal transaction is WPI_SVC_CANCEL_PAYMENT. To reverse a transaction, you need the paymentSolutionReference you retrieve in the response of the transaction that shall be reversed.

Field Name	Type	Condition
`paymentSolutionReference`	String	Mandatory
`reference`	String	Optional
`receiptFormat`	Array	Optional

Example Request:

{
  "paymentSolutionReference": "PaymentSolRef-013543-22234;kjhj3ll3jJHGGSk",
  "reference": "myRef_01"
}

* It is possible to reverse only the last Payment transaction * Reversal does not need card tapping - the full amount will be reversed to the card that initiated the transaction

3.2.3 Refund

The Service Type for a refund transaction is WPI_SVC_REFUND. A refund transaction is like a reversal but just for a partial amount. The requestedAmount specified needs to be equal or lower than the original one.

Field Name	Type	Condition
`currency`	String	Mandatory
`requestedAmount`	Integer	Mandatory
`paymentSolutionReference`	String	Mandatory
`reference`	String	Optional
`receiptFormat`	Array	Optional

Example Request:

{
  "currency": "EUR",
  "requestedAmount": 399,
  "paymentSolutionReference": "PaymentSolRef-013543-22234-kjhj3ll3jJHGGSk",
  "reference": "myRef_01"
}

* It is possible to refund a Payment transaction that is not reversible (all but the last one) * Refund requires card tapping * For transactions with multiple items or services, it is possible to process only one refund (for total or partial amount)

3.3 Information

Retrieval of Payment Solution specific information that does not require user interaction. The request does not contain any parameter.

3.3.1 Last Transaction

In case the last payment transaction response is not known anymore, 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.

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

Request:

Extra	Description	Type	Condition
`WPI_SERVICE_TYPE`	`WPI_SVC_LAST_TRANSACTION`	String	Mandatory
`WPI_VERSION`	Used WPI version	String	Mandatory
`WPI_SESSION_ID`	The session id of the requested session (NOT a new session id)	String	Mandatory

Response:

Extra	Description	Type	Condition
`WPI_SERVICE_TYPE`	This will be the service type of the recovered transaction (not `WPI_SVC_LAST_TRANSACTION`)	String	Conditional - Mandatory if Session id known by the payment solution and transaction was executed
`WPI_RESPONSE`	The Financial Payment Response object of the corresponding `SESSION_ID`	String	Conditional - Mandatory if Session id known by the payment solution and transaction was executed
`WPI_VERSION`	Used WPI version	String	Mandatory
`WPI_SESSION_ID`	Identifier of a WPI exchange (same as the one sent in the request)	String	Mandatory

3.3.2 Receipt Format

Value (String)	Purpose	Tap on Mobile App Behavior
`FORMATTED`	Return the receipt in a payment response as String (default)	No confirmation/receipt details screen after completing transaction; FormattedReceipt contains all the data
`JSON`	Return the receipt in a payment response as JSON	No confirmation/receipt details screen after completing transaction; Receipt field contains JSON data
Empty Array	The payment solution provides the receipt as configured in TMS	Confirmation/receipt details screen is displayed after completing transaction; no receipt data sent back to ECR application

3.4 Transaction Response Description

Each financial transaction has a minimum set of fields that needs to be there per service type.

Response Fields:

Field Name	Description	Type	Condition
`result`	Result of the transaction (success or failure)	String	Mandatory
`errorCondition`	Specific error reason	String	Mandatory
`remark`	Terminal/transaction specific message for detailed error descriptions (English)	String	Conditional - only for NOT successful transaction
`actionCode`	Action code	String	Conditional - only for successful transaction
`timestamp`	Date and time of the transaction (ISO 8601)	String	Conditional - only for successful transaction
`currency`	Currency code (ISO 4217, e.g. EUR)	String	Conditional - only for successful transaction
`authorizedAmount`	Amount of the transaction	String	Conditional - only for successful transaction
`brandName`	Brand name of used payment method	String	Conditional - only for successful transaction with payment card
`customerLanguage`	Language code (ISO 639-1 alpha-2)	String	Optional
`applicationIdentifier`	Payment card application identifier (e.g. A00000041010 for MasterCard)	String	Conditional - only for successful transaction with payment card
`applicationLabel`	Payment card application label (e.g. MasterCard DEBIT)	String	Conditional - only for successful transaction with payment card
`receipt`	Receipt object	Object	Conditional - Always present for successful transactions
`paymentSolutionReference`	Transaction specific and unique identification	String	Conditional - Always present for successful transactions
`reference`	Reference sent in the request	String	Optional
`acquirerIdentifier`	Identifier for the acquirer	String	Conditional
`merchantIdentifier`	Merchant identifier	String	Mandatory
`terminalIdentifier`	Terminal identifier	String	Mandatory
`authorizationCode`	ISO response code + acquirer authorization code	String	Conditional - for online transactions
`tipAmount`	Tip amount	Integer	Conditional - if tip is active
`dccUsed`	DCC was used	Boolean	Conditional
`dccOffered`	DCC was offered	Boolean	Conditional
`dccAmount`	DCC amount	Integer	Conditional
`dccCurrency`	DCC currency	String	Conditional
`dccExchangeRate`	DCC exchange rate	String	Conditional
`authorizationMode`	Authorization mode	String	Conditional - for successful transaction
`pan`	Truncated PAN with last 4 digits	String	Conditional - for successful transaction
`cardholderVerificationMethod`	CVM used	String	Conditional - for successful transaction
`cardDataInput`	How card data was obtained	String	Conditional - for successful transaction

3.4.1 Result

Result	Description
`WPI_RESULT_SUCCESS`	In case of successful transaction
`WPI_RESULT_FAILURE`	In case of failed transaction

3.4.2 Error Conditions

Error Condition	Description
`WPI_ERR_COND_NONE`	No error occurred
`WPI_ERR_COND_SERVICE_NOT_SUPPORTED`	The requested service type is not supported
`WPI_ERR_COND_ABORTED`	The initiator sent an abort request
`WPI_ERR_COND_BUSY`	The Payment Application is busy
`WPI_ERR_COND_CARD_READ_ERR`	Unable to read the card
`WPI_ERR_COND_USER_CANCEL`	The user aborted the transaction
`WPI_ERR_COND_USER_TIMEOUT`	Timeout while waiting for user interaction
`WPI_ERR_COND_HOST_REFUSAL`	The Acquirer/Issuer refused the transaction
`WPI_ERR_COND_NETWORK_ISSUE`	Network issue occurred
`WPI_ERR_COND_TRANSACTION_TIMEOUT`	Timeout during transaction
`WPI_ERR_COND_ENCRYPTION_ISSUE`	Encryption issue
`WPI_ERR_COND_INVALID_KEY`	Missing key in secure component
`WPI_ERR_COND_INVALID_TRANSACTION_REQ`	Invalid transaction request
`WPI_ERR_COND_INTERNAL`	Internal error
`WPI_ERR_COND_INVALID_AMOUNT`	Invalid amount
`WPI_ERR_COND_INVALID_CURRENCY`	Invalid currency
`WPI_ERR_COND_APP_NOT_SUPPORTED`	Card application not accepted
`WPI_ERR_COND_MISSING_MANDATORY_PARAMETER`	Missing mandatory parameter
`WPI_ERR_COND_GENERIC`	Generic error
`WPI_ERR_COND_WPI_VERSION_NOT_SUPPORTED`	WPI version not supported
`WPI_ERR_COND_SESSION_ID_ALREADY_IN_USE`	Session ID already used
`WPI_ERR_COND_INVALID_PASSWORD`	Incorrect password
`WPI_ERR_COND_RECEIPT_DELEGATION_NOT_SUPPORTED`	Receipt delegation not supported
`WPI_ERR_COND_MANUAL_PAN_KEY_ENTRY_NOT_SUPPORTED`	Manual PAN entry not supported
`WPI_ERR_COND_TIP_NOT_SUPPORTED_BY_PAYMENT_SOLUTION`	Tip not supported by payment solution
`WPI_ERR_COND_TIP_NOT_SUPPORTED_BY_SERVICE_TYPE`	Tip not supported for service type
`WPI_ERR_COND_TIP_NOT_SUPPORTED_BY_BRAND`	Tip not supported by card brand
`WPI_ERR_COND_TIP_AMOUNT_EXCEEDS_MAXIMUM`	Tip amount exceeds maximum

3.4.3 Action Codes

Action Code	Description
`WPI_ACTION_CODE_NONE`	No additional action to be performed

3.4.4 Brand Name

Mapping should be based on Payment Application configuration returned by Acquirer.

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_GIROCARD`
`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_OTHER`
`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`

3.4.5 Receipt

Field Name	Description	Type
`formatted`	Merchant and cardholder receipt as preformatted text	JSON object
`json`	Merchant and cardholder receipt in JSON format for custom formatting	JSON object

Custom receipt format should be compliant with local, payment solution and EMV specifications!

3.4.6 Authorization Mode

Authorization Mode	Description
`WPI_AUTHORIZATION_MODE_ONLINE`	Authorized online

3.4.7 Cardholder Verification Method

CVM	Description
`WPI_CVM_NO_CVM`	No CVM executed
`WPI_CVM_PIN_ONLINE`	PIN online CVM executed
`WPI_CVM_CD_CVM`	Consumer Device CVM

3.4.8 Card Data Input

Card Data Input	Description
`WPI_CARD_DATA_INPUT_ALTERNATIVE_PAYMENT_METHOD`	Alternative payment method (e.g. QR Code)
`WPI_CARD_DATA_INPUT_PROXIMITY_ICC`	NFC with chip mode
`WPI_CARD_DATA_INPUT_PROXIMITY_MAGNETIC_STRIPE`	NFC with magnetic stripe mode
`WPI_CARD_DATA_INPUT_REFERENCE_BASED`	Card data from a previous referenced transaction

3.5 Sample Transaction Receipt

Tap on Mobile application has its own transaction receipt handling and it supports:

Sending it via email
Generating QR Code with the link to the digital receipt on the server

Each response contains a transaction receipt for merchants and cardholders. Below is an example of the formatted receipt:

{
  "formatted": {
    "merchant": "    This is to confirm your transaction\n    registered at:\n    ----------------------------------------\n            SPS-Softpos Pilot 02\n              Grzybowska 4/246\n              00-131 Warszawa\n    ----------------------------------------\n    15.02.2023 22:36\n    0,03 PLN\n    Visa **** **** **** 7984\n           Transaction details: \n    Status:                       AUTHORIZED\n    Authorization code:           (0) 741451\n    ARQC:                   61BC5EDC34F63979\n    AID:                      A0000000031010\n    Contactless\n    Type:                               Sale\n    POS ID:                         APP00002\n    MID:                           103810047\n    VISA CARD",
    "client": "    This is to confirm your transaction\n    registered at:\n    ----------------------------------------\n          SPS-Softpos Pilot 02\n                Grzybowska 4/246\n                00-131 Warszawa\n    ----------------------------------------\n    15.02.2023 22:36\n    0,03 PLN\n    Visa **** **** **** 7984\n          Transaction details: \n    Status:                       AUTHORIZED\n    Authorization code:           (0) 741451\n    ARQC:                   61BC5EDC34F63979\n    AID:                      A0000000031010\n    Contactless\n    Type:                               Sale\n    POS ID:                         APP00002\n    MID:                           103810047\n    VISA CARD"
  }
}

As specified in the JSON specification (RFC 4627), every control character has to be escaped.

WMI Documentation

Worldline Management Interface for terminal registration

Test Cards

Test cards for sandbox testing

Sample Apps

Sample applications for reference

SmartPOS WPI

SmartPOS WPI documentation (foundation)

Table of Contents​

1. Introduction​

1.1 Supported Transaction Types​

1.2 Preconditions​

1.3 Versioning​

2. Communication Layer​

2.1 Android Inter App Communication​

2.1.1 Interface Structure​

2.1.2 Android Intent Implementation​

3. Data Dictionary​

3.1 Service Type​

3.2 Transaction Data​

3.2.1 Purchase​

TIP Handling​

3.2.2 Reversal/Cancellation​

3.2.3 Refund​

3.3 Information​

3.3.1 Last Transaction​

3.3.2 Receipt Format​

3.4 Transaction Response Description​

3.4.1 Result​

3.4.2 Error Conditions​

3.4.3 Action Codes​

3.4.4 Brand Name​

3.4.5 Receipt​

3.4.6 Authorization Mode​

3.4.7 Cardholder Verification Method​

3.4.8 Card Data Input​

3.5 Sample Transaction Receipt​

Related Resources​

Table of Contents

1. Introduction

1.1 Supported Transaction Types

1.2 Preconditions

1.3 Versioning

2. Communication Layer

2.1 Android Inter App Communication

2.1.1 Interface Structure

2.1.2 Android Intent Implementation

3. Data Dictionary

3.1 Service Type

3.2 Transaction Data

3.2.1 Purchase

TIP Handling

3.2.2 Reversal/Cancellation

3.2.3 Refund

3.3 Information

3.3.1 Last Transaction

3.3.2 Receipt Format

3.4 Transaction Response Description

3.4.1 Result

3.4.2 Error Conditions

3.4.3 Action Codes

3.4.4 Brand Name

3.4.5 Receipt

3.4.6 Authorization Mode

3.4.7 Cardholder Verification Method

3.4.8 Card Data Input

3.5 Sample Transaction Receipt

Related Resources