worldline

Documentation

Worldline Payment Interface

Version 2.1 | Revision #7

Table of Contents

1 Overview

The Worldline Payment Interface (WPI) is an Android intent-based interface that enables easy and fast integration with payment apps. It is designed to allow additional business applications to execute payments on any Worldline offered SmartPOS device. A SmartPOS device is a payment device that runs Android.

All Worldline Payment Solutions support WPI, which means that business applications that use this interface can run everywhere without any change of code. This makes it easy for developers to build payment apps that are compatible with a wide range of payment devices and payment protocols.

The WPI interface is built on top of the Android Intent mechanism, which allows different parts of an app to communicate with each other in a structured way. By using intents to trigger payment-related actions, the WPI interface simplifies the payment integration process and makes it easier for developers to build business applications on top of Payment Solutions.

1.1 What's new

  • Information functional extensions:

    • Conditions for ShopInfo added

    • Conditions for PaymentInformationItem added

  • Management functional extensions:

    • Payment Solution Information request

      • supportsManualPanKeyEntry flag added

      • supportsTip flag added

  • Financial extensions

    • Follow on Payment added

    • Request fields added

      • cashbackAmount

      • tipAmount

      • useManualPanKeyEntry

      • receiptDelegation

      • receiptFormat

      • customerLanguage

    • Response fields added

      • acquirerIdentifier

      • merchantIdentifier

      • authorizationCode

      • dccOffered

      • dccCurrency

      • dccExchangeRate

      • authorizationMode

      • entryMode

      • terminalIdentifier

      • pan

      • cashbackAmount

      • cardholderVerificationMethod

      • cardDataInput

  • General changes

    • brandName changed to pre-defined

    • Chapter name reservation changed to pre-authorization

    • JSON receipt structure extended with new fields

1.2 Revision History

  • Revision #7

    • 3.1 Financial

      • reference  field restored in Response table

    • 3.3.2 Payment Solution Information

      • supportsReceiptDelegation corrected to supportReceiptDelegation to support receipt delegation as per previous WPI version

    • 4.2 Response Data

      • supportReceiptDelegation description restored

    • Sections numbering fixed

      • 2.1 Extras to 2.2 Extras (with sub-sections)

      • 3.1.9 Payment Instrumentation Recognition to 3.1.8 Payment Instrumentation Recognition

      • 3.1.10 Follow on Credit to 3.1.9 Follow on Credit

      • 3.1.11 Follow on Payment to 3.1.10 Follow on Payment

      • 3.2.4 Print Receipt to 3.2.5 Print Receipt

      • 3.2.5 Abort Ongoing Payment to 3.2.6 Abort Ongoing Payment

  • Revision #6

    • 2.1 Versioning

      • Clarification added on Major and Minor versions (Examples updated)

    • 3.1 Financial

      • acquirerIdentifier presence changed from Mandatory to Conditional

      • entryMode  presence updated (description)

    • 3.1.9 Payment Instrumentation Recognition 

      • Description updated "The payment solution needs information about the transaction service type, requested amount, currency and reference that shall be used for the subsequent transaction"

    • 3.1.10 Follow on Credit

      • Description updated ("Reference of the card" part replaced)

    • 3.1.11 Follow on Payment

      • Description updated ("Reference of the card" part replaced)

    • 4.1 Request Data

      • Description updated for  customerLanguage

      • Description updated for  receiptWidth

    • 4.2 Response Data

      • Description updated for  timestamp

    • 4.2.7 Supported Technologies

      • WPI_ENTRY_MODE_MANUAL value added

    • 4.2.9 Acquirer Protocol

      • MULTI-ACQUIRER value added

  • Revision #5

    • 4.2 Response Data (Data Dictionary)

      • Clarification added on the content of isoTrack1, isoTrack2, IsoTrack3

    • 4.2.6 Payment Information Item

      • Fields startBinRange and endBinRange removed

    • 5.2.b Payment Solution Reference

      • Additional clarification added (i.e. mandatory presence in plain text or QR Code, requirement applicable for cardholder receipt)

    • Product Records feature removed

      • Note: It was reported this feature was not implemented correctly for all payment protocols and/or these implementations vary in term of actual behaviour. Therefore, it is currently removed from the specification. Please contact Worldine support team in case you consider this feature for your business project.

      • Affected sections:

        • 3.1 Financial (Field productRecords removed from response)

        • 3.1.1 Payment (Field productRecords  removed from request)

        • 3.1.7.2 Completion (Field productRecords  removed from request)

        • 4.1 Request Data (Field productRecords  removed from request)

        • 4.1.1 Product Record Item section removed

        • 4.2.5 Receipt (Field  productRecords removed from JSON example)

  • Revision #4

    • 3.1 Financial

      • brandName presence restored to Conditional from Optional

    • 4.2.11 Brand Name

      • Clarification added for non-matching and local brands

    • 4.2.13 Cardholder Verification Method

      • WPI_CVM_PIN_OFFLINE_AND_SIGNATUR E value added

    • 4.2.5 Receipt

      • JSON format example updated

    • 4.2.6 Payment Information Item

      • Clarification on  numberOfCancellableTransactions usage added

    • 5.2.b Payment Solution Reference

      • Clarification added for QR Code printed on the receipt

  • Revision #3

    • 3.1 Financial

      • brandName presence in Response changed from Conditional to Optional

    • 4.2.11 Brand Name

      • WPI_BRAND_NAME_OTHER value added

  • Revision #2

    • 2. Interface Structure

      • Clarified the use of messenger service for background actions

    • 3.1.5 Update Pre-authorization / 3.1.6 Payment Completion

      • Clarification on paymentSolutionReference usage provided

    • 3.1.9 Payment Instrumentation Recognition

      • isoTrack1 and isoTrack2 data types changed to String in Response

  • Revision #1

    • Document Creation

2 Interface Structure

The WPI provides a set of intents that developers can use to build apps that work with the interface. The following table lists each intent, along with its purpose:

Type

Category

Intent

Purpose

Financial

Display Action

com.worldline.payment.action.PROCESS_TRANSACTION

Process a financial transaction

Management

Display Action

com.worldline.payment.action.PROCESS_MANAGEMENT

Trigger payment solution managed actions

Information

Background Action

com.worldline.payment.action.PROCESS_INFORMATION

Background management of payment solution specific information

We have two type of categories for the Interface

  • Display Actions : These actions start the payment solution that are processing financial transactions or require user interaction.

  • Background Actions : These actions perform background processing that doesn't require user interaction.

    • Messenger service is used

    • The Message.what attribute of the Messenger Service should be set to the code 895349 for any WPI message.

    • The Message.obj should be  a bundle formatted just like the WPI Extras.

    • Those extras are being transported through a different mean but the same structure and rules applies

2.1 Versioning

The WPI uses versioning with the format Y.X (e.g., 1.0 , 2.1 ) to track and manage different releases of our software. Additionally, each revision within a minor version is assigned a unique number, such as " 3.2 Revision #9 ."

  • 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 are backward compatible within the same major version. Example: a version 1.1 must remain compatible with the version 1.0 .

  • Revision Number: Each revision is assigned a unique number, indicating the specific iteration of a minor version (e.g., " 3.2 Revision #9 "). Revisions mainly include small fixes, updates, and improvements. They address minor bugs or add slight enhancements/clarifications.

2.2 Extras

An extra in Android intents is a way to pass additional data or parameters to another component in order to provide more context or information for the requested action. In WPI we have extras for request and response. The request extras needs to be provided by the Business Application that is using the interface and the response extra is provided by the Payment Solution.

Request

Extra

Description

Type

Condition

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. Is provided by the client and is part of the response. 

The session id :

  • must be unique

  • must be part of the response

  • must not be reused for subsequent requests (except for the last transaction request as it is used to do the recovery)

Any business application should store the WPI_SESSION_ID before sending the intent. Due to this the business application can do a recovery with the last transaction function to check the outcome of the previous transaction in case that the business application has crashed.

String

Mandatory

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, in some specific cases this field is not given or empty

String

  • Mandatory for Financial

  • Optional for Management

Response

Extra

Description

Type

Condition

WPI_SERVICE_TYPE

Specify the subtype of action that was 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

2.2.1 Service Types

Each intent has several service types that specify the request

2.2.1.1 Financial

Service Type

Purpose

WPI_SVC_PAYMENT

Used to perform a simple sale transaction

WPI_SVC_CANCEL_PAYMENT

Used to reverse a previous transaction

WPI_SVC_REFUND

Used to refund a previous transaction

WPI_SVC_PRE_AUTHORIZATION

Used to perform a pre-authorization

WPI_SVC_CANCEL_PRE_AUTHORIZATION

Used to cancel a previous pre-authorization

WPI_SVC_UPDATE_PRE_AUTHORIZATION

Used to increment a previous pre-authorization

WPI_SVC_CANCEL_UPDATE_PRE_AUTHORIZATION

Used to cancel the previous update of a pre-authorization

WPI_SVC_PAYMENT_COMPLETION

Used to complete a pre-authorization

WPI_SVC_CANCEL_PAYMENT_COMPLETION

Used to cancel the completed pre-authorization

WPI_SVC_DEFERRED_PAYMENT_AUTHORIZATION

Used to execute a deferred payment authorization (energy solution use-case)

WPI_SVC_DEFERRED_PAYMENT_COMPLETION

Used to execute a deferred payment completion of a previous authorization(energy solution use-case)

WPI_SVC_PAYMENT_INSTRUMENT_RECOGNITION

Used to do a payment card of non payment card recognition request without performing a real transaction (token)

WPI_SVC_FOLLOW_ON_CREDIT

Used to do a referenced based credit transaction based on a previous transaction.

WPI_SVC_FOLLOW_ON_PAYMENT

Used to do a referenced based payment transaction based on a previous transaction.

2.2.1.2 Management

Service Type

Purpose

WPI_SVC_PAYMENT_MENU

Used to open the payment solution menu

WPI_SVC_DAY_END

Used to upload the transactions (online and offline) to perform the final settlement. 

WPI_SVC_PAYMENT_PARAMETERIZATION

Used to fetch the latest payment solution configuration from the payment solution related configuration system.

WPI_SVC_ACQUIRER_PARAMETERIZATION

Used to fetch the latest acquirer parameters from the acquirer

WPI_SVC_PRINT_RECEIPT

Used for receipt printing

WPI_SVC_ABORT

Used to abort an ongoing transaction

2.2.1.3 Information

Service Type

Purpose

WPI_SVC_LAST_TRANSACTION

Used to return the last transaction result

WPI_SVC_PAYMENT_INFORMATION

Used to retrieve the payment solution information especially which service types are supported.

3 Interface Description

Please refer to Data Dictionary section for detailed description of individual fields 

3.1 Financial

Each financial transaction has a minimum set of fields that needs to be there per service type. In the subsequent chapters this is described in detail. 

The response contains the following fields:

Response

Field Name

Type

Condition

result

String

Mandatory

errorCondition

String

Mandatory

reference

String

Conditional

  • Mandatory for transactions that sent reference in the request

remark

String

Conditional
- only for not successful transactions

actionCode

String

Conditional
- only for successful transactions

timestamp

String (ISO8601)

Conditional
- only for successful transactions

currency

String

Conditional
- only for successful transactions

authorizedAmount

Integer

Conditional
- only for successful transactions

customerLanguage

String

Conditional
- only for successful transactions in which a payment card was used
(e.g. on reference based transactions the card is not inserted and therefore we cannot get these data)

brandName

String

(pre-defined 4.2.11 Brand Name)

Conditional
- only for successful transactions in which a payment card was used
(e.g. on reference based transactions the card is not inserted and therefore we cannot get these data)

applicationIdentifier

String

Conditional
- only for successful transactions in which a payment card was used
(e.g. on reference based transactions the card is not inserted and therefore we cannot get these data)

applicationLabel

String

Conditional
- only for successful transactions in which a payment card was used
(e.g. on reference based transactions the card is not inserted and therefore we cannot get these data)

receipt

Object

(5.2.5 Receipt)

Conditional
- always present for successful transactions
- optional for failed transactions

paymentSolutionReference

String

Conditional
- always present for successful transactions
- optional for failed transactions

acquirerIdentifier

String

Conditional
- always present for successful transactions
- optional for failed transactions

merchantIdentifier

String

Mandatory

terminalIdentifier

String

Mandatory

authorizationCode

String

Conditional
- in case of transaction was processed online

cashbackAmount

Integer

Conditional
- in case of cashback is activated and amount is given in request

tipAmount

Integer

Conditional
- in case of tip is active and entered by the cardholder during transaction processing or provided in the request 

dccUsed

Boolean

Conditional
- in case of DCC was selected by the cardholder

dccOffered

Boolean

Conditional
- in case of DCC is active and DCC selection was shown towards the cardholder

dccAmount

Integer

Conditional
- in case of DCC is active and the cardholder has selected his own currency

dccCurrency

String

Conditional
- in case of DCC is active and the cardholder has selected his own currency

dccExchangeRate

String

Conditional
- in case of DCC is active and the cardholder has selected his own currency

entryMode

String (pre-defined 4.2.7 Supported Technologies)

Conditional
- in case of successful and non-reference based transaction

-optional if  cardDataInput already present in the response

authorizationMode

String (pre-defined 4.2.10 Authorization Mode)

Conditional
- in case of successful transaction

pan

String

Conditional
- in case of successful transaction

cardholderVerificationMethod

String (pre-defined 4.2.13 Cardholder Verification Method)

Conditional
- in case of successful transaction

cardDataInput

String (pre-defined 4.2.12 Card Data Input)

Conditional
- in case of successful transaction

3.1.1 Payment

Service Type: WPI_SVC_PAYMENT

Request

Field Name

Type

Condition

currency

String

Mandatory

requestedAmount

Integer

Mandatory

tipAmount

Integer

Optional

cashbackAmount

Integer

Optional

reference

String

Optional

customerLanguage

String

Optional

useManualPanKeyEntry

Boolean

Optional

receiptFormat

Array

(of pre-defined 4.1.1 Receipt Format)

Optional

receiptDelegation

Boolean

Optional

receiptWidth

Integer

Optional

3.1.2 Cancellation

The cancellation is also known as reversal. The cancellation can be executed for several service types, the cancellation service type depends on the initial service type and needs to be set and used correctly by the business application.

Service Type : WPI_SVC_CANCEL_PAYMENT, WPI_SVC_CANCEL_PRE_AUTHORIZATION, WPI_SVC_CANCEL_UPDATE_PRE_AUTHORIZATION, WPI_SVC_CANCEL_PAYMENT_COMPLETION

Request

Field Name

Type

Condition

paymentSolutionReference

String

Mandatory

customerLanguage

String

Optional

receiptFormat

Array (of pre-defined 4.1.1 Receipt Format)

Optional

receiptDelegation

Boolean

Optional

receiptWidth

Integer

Optional

3.1.3 Refund

Service Type : WPI_SVC_REFUND

Request :

Field Name

Type

Condition

currency

String

Mandatory

requestedAmount

Integer

Mandatory

reference

String

Optional

customerLanguage

String

Optional

useManualPanKeyEntry

Boolean

Optional

receiptFormat

Array (of pre-defined 4.1.1 Receipt Format)

Optional

receiptDelegation

Boolean

Optional

receiptWidth

Integer

Optional

3.1.4 Pre-authorization

Service Type : WPI_SVC_PRE_AUTHORIZATION

Request :

Field Name

Type

Condition

currency

String

Mandatory

requestedAmount

Integer

Mandatory

reference

String

Optional

customerLanguage

String

Optional

useManualPanKeyEntry

Boolean

Optional

receiptFormat

Array (of pre-defined 4.1.1 Receipt Format)

Optional

receiptDelegation

Boolean

Optional

receiptWidth

Integer

Optional

3.1.5 Update Pre-authorization

This service is used to increase the pre-authorization amount, which involves specifying the requested amount for the increment. The reference of pre-authorization is provided through the paymentSolutionReference , which will be use to make the update pre-authorization. The requestedAmount is just the amount that shall be incremented, not the total one

Service Type : WPI_SVC_UPDATE_PRE_AUTHORIZATION

Request :

Field Name

Type

Condition

currency

String

Mandatory

requestedAmount

Integer

Mandatory

paymentSolutionReference

String

Mandatory

reference

String

Optional

customerLanguage

String

Optional

receiptFormat

Array (of pre-defined 4.1.1 Receipt Format)

Optional

receiptDelegation

Boolean

Optional

receiptWidth

Integer

Optional

3.1.6 Payment Completion

To complete a previous pre-authorization the paymentSolutionReference has to be used. The final amount should be equal to or less than the total pre-authorization amount (this includes all previous Update pre-authorization calls). If you use a higher amount for the completion, the transaction may not be successful because the higher amount was not reserved - we do not recommend to use higher amounts.

Service Type : WPI_SVC_PAYMENT_COMPLETION

Request :

Field Name

Type

Condition

currency

String

Mandatory

requestedAmount

Integer

Mandatory

paymentSolutionReference

String

Mandatory

reference

String

Optional

customerLanguage

String

Optional

receiptFormat

Array (of pre-defined 4.1.1 Receipt Format)

Optional

receiptDelegation

Boolean

Optional

receiptWidth

Integer

Optional

3.1.7 Deferred Payment

Deferred payment for petrol transaction processing refers to a payment arrangement where the actual payment for fuel is delayed or postponed until a later time. The transaction is split into two parts: authorization and completion.

  1. Authorization: The first part of the deferred payment process is authorization. When a customer swipes their payment card or provides their payment details at the petrol station, the system checks if the card is valid and has sufficient funds or credit available. This initial authorization ensures that the customer's payment method is valid and can cover the cost of the fuel. However, the actual payment is not processed at this stage.

  2. Completion: The second part of the deferred payment process is completion. After the authorization is successful, the petrol station temporarily reserves the funds or credit limit on the customer's card to cover the estimated cost of the fuel. This reserved amount is typically a pre-authorization hold or pending transaction. The petrol station then dispenses the fuel to the customer.

Later, the petrol station completes the transaction by submitting the final payment request to the customer's bank or credit card company. At this stage, the reserved funds are transferred from the customer's account to the petrol station's account, completing the payment process. The exact timing for completing the authorization may vary depending on the specific payment system and agreements between the petrol station and the customer's financial institution.

The delay between the “Authorization Exchange” and the “Completion Exchange” can be quite long (e.g., in case of tank filling). Therefore, to increase the availability of the terminals using the “Deferred Payment” service, the “Multi-Session” concept is usually configured for performing “Parallel Transactions”. The authorization exchange provides the terminal with an authorized amount as upper limit, and the completion exchange notifies the acquirer of the final amount as actually applicable. The “Deferred Payment” is indifferently meant for attended or unattended terminals. 

PSD2 imposes the amount to be present in the request.

3.1.7.1 Authorization

Service Type : WPI_SVC_DEFERRED_PAYMENT_AUTHORIZATION

Request :

Field Name

Type

Condition

currency

String

Mandatory

requestedAmount

Integer

Mandatory

reference

String

Optional

customerLanguage

String

Optional

3.1.7.2 Completion

Service Type : WPI_SVC_DEFERRED_PAYMENT_COMPLETION

Request :

Field Name

Type

Condition

currency

String

Mandatory

requestedAmount

Integer

Mandatory

paymentSolutionReference

String

Mandatory

reference

String

Optional

customerLanguage

String

Optional

receiptFormat

Array (of pre-defined 4.1.1 Receipt Format)

Optional

receiptDelegation

Boolean

Optional

receiptWidth

Integer

Optional

3.1.8 Payment Instrumentation Recognition

The intention is to avoid double tap under the condition the payment instrument is a contactless entry mode. The payment solution needs information about the transaction service type, requested amount, currency and reference that should be used for the subsequent transaction. There are two possibilities to do a payment instrumentation recognition token retrieval only and card recognition with further payment processing afterwards. The response differs from the standard response as described below. 

Service Type : WPI_SVC_PAYMENT_INSTRUMENT_RECOGNITION

Request :

Field Name

Type

Condition

currency

String

Optional
- in case of transaction processing should happen afterwards

requestedAmount

Integer

Optional
- in case of transaction processing should happen afterwards

serviceType

String

Optional
- in case of transaction processing should happen afterwards

cashbackAmount

Integer

Optional
- in case of transaction processing should happen afterwards
- in case of the requested service type supports cashback

tipAmount

Integer

Optional
- in case of transaction processing should happen afterwards
- in case of the requested service type or payment solution supports tip

recognitionTimeout

Integer

Mandatory

recognitionOptions

Array

Mandatory

customerLanguage

String

Optional

Response :

Data Field

Type

Condition

result

String

Mandatory

errorCondition

String

Mandatory

entryMode

String

Conditional
- (Mandatory) in case of  WPI_RESULT_SUCCESS 

customerLanguage

String

Conditional
- (Mandatory) in case of  WPI_RESULT_SUCCESS 

isoTrack1

String

Conditional
- in case of magnetic stripe card  

isoTrack2

String

Conditional
- in case of magnetic stripe card 

isoTrack3

String

Conditional
- in case of magnetic stripe card 

token

String

Conditional
- (Mandatory) in case of payment card processing

pan

String

Conditional
- (Mandatory) in case of payment card processing

mediaType

String

Conditional
- in case of non payment card processing

mediaUniqueIdentifier

String

Conditional
- in case of non payment card processing

waitForNextAction

Boolean

Conditional
- (Mandatory) in case of  WPI_RESULT_SUCCESS

nextActionWaitTime

Integer

Conditional
- (Mandatory) in case of  WPI_RESULT_SUCCESS

3.1.9 Follow On Credit

Follow on Credit is a card not present transaction which is used to perform the credit transaction with the card data of a previous transaction. paymentSolutionReference is used to identify data necessary to perform follow-up transaction.

Service Type : WPI_SVC_FOLLOW_ON_CREDIT

Request :

Field Name

Type

Condition

currency

String

Mandatory

requestedAmount

Integer

Mandatory

reference

String

Optional

paymentSolutionReference

String

Mandatory

customerLanguage

String

Optional

receiptFormat

Array (of pre-defined 4.1.1 Receipt Format)

Optional

receiptDelegation

Boolean

Optional

receiptWidth

Integer

Optional

3.1.10 Follow on Payment

Follow on Payment is a card not present transaction which is used to perform the payment transaction with the card data of a previous transaction. paymentSolutionReference is used to identify data necessary to perform follow-up transaction.

Service Type : WPI_SVC_FOLLOW_ON_PAYMENT

Request :

Field Name

Type

Condition

currency

String

Mandatory

requestedAmount

Integer

Mandatory

reference

String

Optional

paymentSolutionReference

String

Mandatory

customerLanguage

String

Optional

receiptFormat

Array (of pre-defined 4.1.1 Receipt Format)

Optional

receiptDelegation

Boolean

Optional

receiptWidth

Integer

Optional

3.2 Management

Management actions has an empty request JSON content, except for services that contain a receipt, like Day-End and the parameterizations. The receipt format can be set in the request with the receiptFormat field (defined in 4.1.1 Receipt Format). If a receipt format is also defined for a management services that does not have a receipt the receiptFormat will be ignored by the payment solution. The same applies to receiptWidth and receiptDelegation .

The response for every management action contains the following fields:

Response :

Field Name

Type

Condition

result

String

Mandatory

errorCondition

String

Mandatory

receipt

Object (5.2.5 Receipt)

Conditional
- only for Management services that contains a receipt

3.2.1 Payment Menu

This is used to open the payment solution menu to trigger payment solution specific actions.

Service Type : WPI_SVC_PAYMENT_MENU

3.2.2 Day-End

The day-end is used to upload all transactions to the host for the final settlement. As result an receipt is received which contains a transaction summary per brand with no. of transactions and amount since the last day-end (incl. online and offline transactions).

Service Type : WPI_SVC_DAY_END

Request :

Field Name

Type

Condition

receiptFormat

Array (of pre-defined 4.1.1 Receipt Format)

Optional

receiptDelegation

Boolean

Optional

receiptWidth

Integer

Optional

3.2.3 Payment Parametrization

The payment configuration is used to synchronize the payment solution specific parameters with the corresponding management system.

Service Type : WPI_SVC_PAYMENT_PARAMETERIZATION

Request :

Field Name

Type

Condition

receiptFormat

Array (of pre-defined 4.1.1 Receipt Format)

Optional

receiptDelegation

Boolean

Optional

receiptWidth

Integer

Optional

3.2.4 Acquirer Parametrization

The Acquirer parameterization is used to synchronize with the acquirer system corresponding to the payment solution. This includes brands, limits and any other parameter that is mandatory to process a financial transaction. Multi-Acquirer solutions will do the parameterization synchronization for all acquirers.

Service Type : WPI_SVC_ACQUIRER_PARAMETERIZATION

Request :

Field Name

Type

Condition

receiptFormat

Array (of pre-defined 4.1.1 Receipt Format)

Optional

receiptDelegation

Boolean

Optional

receiptWidth

Integer

Optional

3.2.5 Print Receipt

This function is intended to provide a compliant receipt by the payment solution. A receipt can be provided in case of

  • A previous service was successfully executed with a corresponding session ID for this business application

  • The SESSION_ID of the print receipt request in the Android Extras has to be the previous request SESSION_ID and not a new one

  • The payment solution supports receipt delivery, for example printing or digital receipt based delivery

  • Referenced request (by SESSION_ID) has a receipt available

The Android Extras in the response are close to a standard transaction response except for the conditional presence of WPI_RESPONSE. An initial check on this extra property provides information about the existence of the session. If not available the session ID is not existing.

Be aware any payment solution will just store the last SESSION_ID and response per application (package name). This implies that no other WPI requests shall be done before printing the receipt.

Hint: The receipt cannot be provided under the following circumstances:

Circumstance

Description

Error Condition

Paper empty

Receipt cannot be printed as the paper is empty

WPI_ERR_COND_GENERIC

Printer defect

Printer cannot be used to reprint the receipt as it is defect

WPI_ERR_COND_GENERIC

Receipt delivery not available

Neither a printer nor a digital receipt is available, mainly happens in unattended environments. The service type support for print receipt can be checked with the 3.3.2 Payment Solution Information

WPI_ERR_COND_SERVICE_NOT_SUPPORTED

Receipt not available

Not every service type has receipts.  For example if the referenced service type was WPI_SVC_PAYMENT_INFORMATION no receipt can be printed. 

WPI_ERR_COND_GENERIC

Service Type : WPI_SVC_PRINT_RECEIPT

Request :

Field Name

Type

Condition

receiptTarget

String (pre-defined 4.1.3 Receipt Target)

Mandatory

Response

Field Name

Type

Condition

result

String (pre-defined 4.2.2 Result)

Mandatory

errorCondition

String (pre-defined 4.2.3 Error Condition)

Mandatory

remark

String

Conditional
- In case of an errorCondition not equal to WPI_ERR_COND_NONE

3.2.6 Abort Ongoing Payment

Abort the current ongoing financial transaction. If the transaction was successfully aborted or there was no running transaction WPI_RESULT_SUCCESS will be returned in all other cases WPI_RESULT_FAILURE .

Service Type : WPI_SVC_ABORT

3.3 Information

Retrieval of Payment Solution specific information that does not require user interaction. There request does not contain any parameter. The response is specific per service type.

3.3.1 Last Transaction

In case of the last 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. 

Service Type : WPI_SVC_LAST_TRANSACTION

Request :

Extra

Description

Type

Condition

WPI_SERVICE_TYPE

Specify the subtype of action to be executed 

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

Session id known by the payment solution and transaction was executed (failure or success)

WPI_RESPONSE

The Financial Payment Response object of the corresponding SESSION_ID

String

Session id known by the payment solution and transaction was executed (failure or success)

WPI_VERSION

Used WPI version

String

Mandatory

WPI_SESSION_ID

Identifier of a WPI exchange

String

Mandatory

3.3.2 Payment Solution Information

The payment should provide all the required information, in case of a lack or issue of configuration / initialization the response should provide the WPI_ERR_COND_NOT_INITIALIZED as an errorCondition .

Service Type : WPI_SVC_PAYMENT_INFORMATION

Response :

Field Name

Description

Type

Condition

result

Result of the transaction (success or failure)

String (pre-defined 4.2.2 Result)

Mandatory

errorCondition

Specific error reason (see table below)

String (pre-defined 4.2.3 Error Condition)

Mandatory

softwareVersion

Software version of the payment solution

String

Conditional
- In case of WPI_RESULT_SUCCESS

terminalIdentifier

Terminal identifier configured for the payment solution

String

Conditional
- In case of WPI_RESULT_SUCCESS

terminalModel

Terminal model of the device

String

Conditional
- In case of WPI_RESULT_SUCCESS

macAddress

MAC Address of used adapter.

String

Conditional
- In case of WPI_RESULT_SUCCESS

supportedLanguages

Languages supported by the payment solution

Array

Conditional
- In case of WPI_RESULT_SUCCESS

cardholderDefaultLanguage

Cardholder language

String

Conditional
- In case of WPI_RESULT_SUCCESS

merchantLanguage

Merchant language 

String

Conditional
- In case of WPI_RESULT_SUCCESS

countryCode

Country code of the payment solution

String

Conditional
- In case of WPI_RESULT_SUCCESS

defaultCurrency

Default currency 

String

Conditional
- In case of WPI_RESULT_SUCCESS

supportedCurrencies

Currencies the payment solution supports

Array

Conditional
- In case of WPI_RESULT_SUCCESS

shopInfo

Shop information for the used terminal

Object (4.2.1 ShopInfo)

Conditional
- In case of WPI_RESULT_SUCCESS

acquirerProtocol

The payment solution protocol used towards the acquirer

String

Conditional
- In case of WPI_RESULT_SUCCESS

supportedTicketFormats

Receipt formats which the payment solution supports

Array

Conditional
- In case of WPI_RESULT_SUCCESS

supportReceiptDelegation

Whether receipt delegation is supported or not.

Boolean

Conditional
- In case of WPI_RESULT_SUCCESS

paymentInformation

Payment information per brand

Array

Conditional
- In case of WPI_RESULT_SUCCESS

paymentSolutionSupportedServiceTypes

Supported services types by the payment solution

Array

Conditional
- In case of WPI_RESULT_SUCCESS

supportsManualPanKeyEntry

Whether manual card data entry through the payment application is activated or not.

Boolean

Conditional
- In case of WPI_RESULT_SUCCESS

supportsTip

Whether tip is supported or not. Tip is supported when the payment solution has tip processing activated and tipAmount can be send in the WPI request. If Payment Solution supports tip but does not support tipAmount returned via WPI this field should be set to False

Boolean

Conditional
- In case of WPI_RESULT_SUCCESS

4 Data Dictionary

The data dictionary contains all possible fields including the description and type for all services. 

4.1 Request Data

All data has to be provided as JSON and needs to be provided as WPI_REQUEST extra.

Field Name

Description

Type

currency

Currency of the amount. Alpha code value defined in ISO 4217 (e.g. EUR )

String

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.

(Cashback and tip amount is excluded)

Integer

tipAmount

The tip amount to be used as minor unit. This amount has the same currency as the transaction amount.

Refer to 5. Tip processing for more information

Integer

paymentSolutionReference

A previous transaction reference used for subsequent transactions like a Reversal. This value is defined by the payment application and contains all necessary data to perform subsequent transactions. This value can differ based on the payment application and can only be used on the same device.

String

reference

Reference to be send to the payment solution for reconciliation

String

receiptFormat

To override the default receipt format.

Array (of pre-defined 4.1.1 Receipt Format)

receiptDelegation

This flag is used to deactivate the payment solution receipt handling. Per default the payment solution will take care about the receipt delivery as configured by the corresponding TMS. To deactivate the payment solution specific receipt handling false has to be set.

Default: true

Boolean

receiptWidth

The receipt width (characters per line) for the formatted receipt. If the value is not defined the payment solution default one will be used.

Please note this field may not be supported by some Payment Solutions and only default width will be available for printing.

Integer

recognitionTimeout

Defines the timeout before an error will be returned in milliseconds

Integer

recognitionOptions

Card recognition options

Array (of pre-defined 4.1.2 Recognition Option)

receiptTarget

Defines the receipt which shall be printed

String (pre-defined 4.1.3 Receipt Target)

cashbackAmount

The cashback amount to be used as minor unit. This amount has the same currency as the transaction amount.

Integer

customerLanguage

Language the payment application shall use. If the language is not supported or not recognized by the payment application the default language of the terminal will be used.

used on all screens towards the cardholder and when formatting the receipt. Language code will be returned for english > en

Format according to ISO 630-1 (alpha-2 code)

String

useManualPanKeyEntry

Flag that will inform the payment solution to offer manual PAN key entry instead of physical card reading. Default: false

Boolean

4.1.1 Receipt Format

The receipt format defines how to retrieve the receipt. Default is formatted. If an empty array is sent no receipt will be returned. The following values are possible:

Value (String)

Description

FORMATTED

Return the receipt in a payment response as String (default)

JSON

Return the receipt in a payment response as JSON

4.1.2 Recognition Option

Value (String)

Description

WPI_RECOGNITION_OPTION_RETURN_CUSTOMER_TOKEN

Used to create a token for the card that was read

WPI_RECOGNITION_OPTION_RETURN_MIFARE_DETAILS

Used to recognize a non payment card, like MIFARE. The UID and card type will be evaluated

4.1.3 Receipt Target

Value (String)

Description

CARDHOLDER

Used to print the cardholder receipt

MERCHANT

Used to print the merchant receipt

BOTH

Used to print the merchant and cardholder receipt one after the other

4.2 Response Data

All data has to be provided as JSON and will be provided as WPI_RESPONSE extra.

Field Name

Description

Type

result

Result of the transaction (success or failure)

String (pre-defined 4.2.2 Result)

errorCondition

Specific error reason (see table below)

String (pre-defined 4.2.3 Error Condition)

actionCode

Specific action to be performed by the business application

String (pre-defined 4.2.4 Action Code)

remark

Terminal / transaction specific message for detailed error descriptions. Text provided by payment app in English

String

timestamp

Date and time of the transaction, indicated by the payment application towards the acquirer.

Format according to ISO 8601 (extended format) =>  yyyy-mm-ddThh:mm:ss±hh:mm

String

currency

Currency code of the transaction. Alpha code value defined in ISO 4217 e.g. EUR

String

authorizedAmount

Amount of the transaction, including tip and cashback. The fraction is taken from the currency code. Example:

currency = EUR
authorizedAmount= 3190
=> 31,90 €

Integer

brandName

Brand name of used payment card, like Mastercard, Visa, American Express and so on.

String (pre-defined 4.2.11 Brand Name)

customerLanguage

Language used on all screens towards the cardholder and when formatting the receipt. Language code will be returned for english > en

Format according to ISO 630-1 (alpha-2 code)

String

applicationIdentifier

Payment card application identifier dependent on the used card e.g. for Mastercard A00000041010

String

applicationLabel

Payment card application label, depending on the used card e.g. Mastercard DEBIT

String

receipt

Contains the requested receipts. Depending on the format for more details check the receipt chapter.

Object (4.2.5 Receipt)

paymentSolutionReference

Transaction specific and unique identification. This value is defined by the payment application and contains all necessary data to perform subsequent transactions. This value can differ based on the payment application and can only be used on the same device.

String

dccUsed

Whether DCC was used or not for the transaction. This field is present as soon as DCC is activated for this payment solution.

Boolean

tipAmount

The tip amount that was entered by the cardholder during the transaction with the payment solution. This field is present as soon as tip is activated for this payment solution.

Integer

reference

Reference to be send to the payment app for reconciliation. The reference will be the same value as in the request.

String

softwareVersion

Payment Solution software version

String

terminalIdentifier

The terminal identifier configured for the payment solution

String

supportedLanguages

List of language that are supported

Format according to ISO 630-1 (alpha-2 code)

Array

cardholderDefaultLanguage

The configured cardholder default language

Format according to ISO 630-1 (alpha-2 code)

String

merchantLanguage

The configured merchant default language

Format according to ISO 630-1 (alpha-2 code)

String

countryCode

The country code of the terminal ISO 3166-1 (alpha-2 code)

String

defaultCurrency

The default currency that is configured for the payment solution.

Alpha code value defined in ISO 4217 e.g. EUR

String

supportedCurrencies

All currencies that are supported by the payment solution.

Alpha code value defined in ISO 4217 e.g. EUR

Array

shopInfo

The shop information of the terminal. Usually these are the first three lines of each receipt.

Object (4.2.1 ShopInfo )

acquirerProtocol

The used acquirer protocol by the payment solution, usually this is the official acronym like CTAP.

String (pre-defined 4.2.9 Acquirer Protocol)

supportedTicketFormats

The supported ticket formats by the payment solution

String (pre-defined 4.1.1 Receipt Format)

supportReceiptDelegation

Whether the payment application supports (True) receipt delegation or not (False). Receipt delegation is when any business application asks the payment solution to handle the receipt. Any payment solution can handle the receipt if a printer or a digital solution is available.

Boolean

paymentInformation

Detailed payment solution information per brand & acquirer

Array (4.2.6 Payment Information)

paymentSolutionSupportedServiceTypes

The service types supported by the payment solution are independent of the card brand. Each payment solution can support multiple service types, but often not every service type is supported by every card brand.

Array (2.1.1.1 Financial Service Types &  2.1.1.2 Management Service Types

entryMode

The technology that was used to read the card

String (pre-defined 4.2.7 Supported Technologies)

isoTrack1

ISO track 1 data 

Payment Solution may return empty field in case of PCI brands (Visa, MasterCard, others)

String

isoTrack2

ISO track 2 data

Payment Solution may return empty field in case of PCI brands (Visa, MasterCard, others)

String

isoTrack3

ISO track 3 data

Payment Solution may return empty field in case of PCI brands (Visa, MasterCard, others)

String

token

The token of the card PAN / UID (in case of NFC non payment related card) that was read. The token should be an unique value, generated by the payment solution and can be reproduced on the same device. This token is used to identify the customer.

String

pan

PAN of the card (due to PCI regulatory payment card PAN data are always masked except last 4 digits). For whitelisted non payment cards the full PAN the unmasked will be used.

String

mediaType

Media type of NFC non payment card. e.g. MIFARE Ultralight

String

mediaUniqueIdentifier

UID of NFC based non payment card

String

waitForNextAction

Whether the payment solution keeps the card in read mode for a subsequent transaction or not

Boolean

nextActionWaitTime

The time how long the card is kept in read mode, in milliseconds

Integer

acquirerIdentifier

The Acquirer Identifier

String

merchantIdentifier

The Merchant Identifier

String

authorizationCode

Authorization code from the authorization system for the specific transaction.

String

dccOffered

Whether DCC was offered to the cardholder or not for the transaction. This field is present as soon as DCC is activated for this payment solution.

Boolean

dccAmount

The DCC amount of the transaction, in case of DCC was used

Integer

dccCurrency

The DCC currency of the transaction, in case of DCC was used

Alpha code value defined in ISO 4217 e.g. EUR

String

dccExchangeRate

The DCC exchange rate of the transaction, in case of DCC was used

String

authorizationMode

Indicating whether the transaction was performed online or offline.

String (pre-defined 4.2.10 Authorization Mode)

cashbackAmount

The cashback amount used in the transaction. (Minor unit)

Integer

cardDataInput

The card data input method

String (pre-defined 4.2.12 Card Data Input)

cardholderVerificationMethod

The cardholder verification method determined during the transaction processing by the payment solution.

String (pre-defined 4.2.13 Cardholder Verification Method)

4.2.1 ShopInfo

Field Name

Description

Type

Condition

name

Name of the shop

String

Optional

address

Address of the shop usually street and number

String

Optional

zipCode

ZIP code of the shop

String

Optional

city

City of the shop

String

Optional

country

Country of the ship

String

Optional

logo

Content provider URI of the logo to be used

String

Optional

4.2.2 Result

Result

Description

WPI_RESULT_SUCCESS

In case of successful transaction

WPI_RESULT_FAILURE

In case of failed transaction

4.2.3 Error Condition

Error Condition

Description

WPI_ERR_COND_NONE

Will always be present if no error occurred

WPI_ERR_COND_SERVICE_NOT_SUPPORTED

The requested service type is not supported by the Payment Application/Service

WPI_ERR_COND_ABORTED

The initiator of the request has sent an abort request, which was accepted and processed.

WPI_ERR_COND_BUSY

The Payment Application/Service is busy. Try later.

WPI_ERR_COND_CARD_READ_ERR

The payment application was not able to read the card. Either due to inconsistent data or wrong card handling.

WPI_ERR_COND_USER_CANCEL

The user has aborted the transaction

WPI_ERR_COND_USER_TIMEOUT

A timeout occurred while waiting for user interaction.

WPI_ERR_COND_HOST_REFUSAL

The Acquirer/Issuer refused the transaction.

WPI_ERR_COND_NETWORK_ISSUE

Network issue occurred (host not reachable, network down, … )

WPI_ERR_COND_TRANSACTION_TIMEOUT

Timeout occurred during transaction (other than with user interaction ).

WPI_ERR_COND_ENCRYPTION_ISSUE

Encryption issue (PAN, PIN …) caused the transaction to be aborted.

WPI_ERR_COND_INVALID_KEY

The secure component of the terminal is missing a key it needs to perform the transaction.

WPI_ERR_COND_INVALID_TRANSACTION_REQ

Invalid transaction request received. One of the fields in the transaction request object was invalid.

WPI_ERR_COND_INTERNAL

Internal error within payment service

WPI_ERR_COND_INVALID_AMOUNT

Entered invalid amount

WPI_ERR_COND_INVALID_CURRENCY

Transaction started with invalid currency. The currency is a global attribute of the underlying payment service.

WPI_ERR_COND_APP_NOT_SUPPORTED

None of the applications on the EMV NFC/IC chip card are accepted or the ISO/PAN on the magnetic stripe track didn’t result in a brand being accepted

WPI_ERR_COND_MISSING_MANDATORY_PARAMETER

A mandatory parameter is missing in the request.

WPI_ERR_COND_GENERIC

A generic error that is not specified in detail

WPI_ERR_COND_NOT_INITIALIZED

The payment solution is not configured and cannot process the request.

WPI_ERR_COND_WPI_VERSION_NOT_SUPPORTED

The request contains a WPI version which is not supported by the payment solution.

WPI_ERR_COND_SESSION_ID_ALREADY_IN_USE

In case of the SESSION ID was already used and the payment solution would not be able to identify the last transaction for recovery then this error code is returned.

WPI_ERR_COND_INVALID_PASSWORD

For password protected transactions, this error code is returned if the password entered in the payment solution, by the merchant, is incorrect.

WPI_ERR_COND_RECEIPT_DELEGATION_NOT_SUPPORTED

If a transaction was started with receipt delegation and receipt delegation is not supported this error code is returned

WPI_ERR_COND_MANUAL_PAN_KEY_ENTRY_NOT_SUPPORTED

In case of manual PAN key entry is not possible but requested.

WPI_ERR_COND_CASHBACK_NOT_SUPPORTED

If a transaction was started with cashback and cashback is not supported

WPI_ERR_COND_TIP_NOT_SUPPORTED_BY_PAYMENT_SOLUTION

If tipAmount is present in the transaction request but not supported by the payment solution

WPI_ERR_COND_TIP_NOT_SUPPORTED_BY_SERVICE_TYPE

If tipAmount is present in the transaction request but not supported for the specific service type

WPI_ERR_COND_TIP_NOT_SUPPORTED_BY_BRAND

If tipAmount is present in the transaction request but not supported by cardholder card brand

WPI_ERR_COND_TIP_AMOUNT_EXCEEDS_MAXIMUM

If tipAmount is higher than the maximum allowed tipAmount configured for the payment solution

4.2.4 Action Code

Action Code

Description

WPI_ACTION_CODE_NONE

No additional action to be performed

WPI_ACTION_CODE_ASK_LEGAL_IDENTIFICATION

Ask the cardholder for a legal identification and write the identification data down on the receipt.

WPI_ACTION_CODE_ASK_SIGNATURE

Ask the cardholder to sign the merchant receipt to complete the authorization.

4.2.5 Receipt

Field Name

Description

Type

formatted

Merchant and cardholder receipt are contained in this field. Both receipts are available as text preformatted. The receipt wide is defined by the payment application (often 32 characters) and depends on the printer capabilities or configuration.

JSON object (check example below)

json

Merchant and cardholder receipt are contained in this field. Both receipts are represented in a JSON format. This is used to create a own format.

An own format should be compliant with the local, payment solution and EMV specification!

JSON object (check example below)

The receipt language is the same as it is for the payment app. As it is written in the JSON specification ( https://www.ietf.org/rfc/rfc4627.txt ) every control character has to be escaped like shown below but on the same line.

FORMATTED format:

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"
    }
}

JSON format:

"json":{
    "receiptTargets":{
        "merchant":{
            "description": "List of field names of the receipt to be included for the merchant receipt"
            "type":"array",
            "items":{
                "type":"string"
            }
        },
        "client":{
            "description": "List of field names of the receipt to be included for the client receipt"
            "type":"array",
            "items":{
                "type":"string"
            }
        }
    },
    "duplicate":{
        "type":"boolean"
    },
    "shopInfo":{
        "name":{
            "type":"string"
        },
        "address":{
            "type":"string"
        },
        "zipCode":{
            "type":"string"
        },
        "city":{
            "type":"string"
        },
        "country":{
            "type":"string"
        },
        "logo":{
            "type":"string" // Content provider uri to the logo file
        }
    },
    "terminalIdentifier":{
        "type":"string"
    },
    "period":{
        "type":"string"
    },
    "transactionIdentifier":{
        "type":"string"
    },
    "currency":{
        "type":"string"
    },
    "amount":{
        "type":"integer"
    },
    "cashbackAmount":{
        "type":"integer"
    }
    "tipAmount":{
        "type":"integer"
    },
    "token":{
        "type":"string"
    },
    "par":{
        "type":"string"
    },
    "brandName":{
        "type":"string"
    },
    "applicationIdentifier":{
        "type":"string"
    },
    "issuerName":{
        "type":"string"
    },
    "pan":{
        "type":"string"
    },
    "maskedPan":{
        "type":"string"
    },
    "cardSequence":{
        "type":"string"
    },
    "cardExpiration":{
        "type":"string"
    },
    "serviceName":{
        "type":"string"
    },
    "timestamp":{
        "type":"string"
    },
    "authorizationCode":{
        "type":"string"
    },
    "reference":{
        "type":"string"
    },
    "acquirerIdentifier":{
        "type":"string"
    },
    "entryMode":{
        "type":"string"
    },
    "cardDataInput":{
        "type":"string"
    },
    "cardholderVerificationMethod":{
        "type":"string"
    },
  "legalIdentificationRequired":{
        "type":"boolean"
    },
    "cardBalance":{
        "old":{
            "type":"string"
        },
        "new":{
            "type":"string"
        },
        "cardholderText":{
            "type":"string"
        }
    },
    "paymentSolutionReference":{
        "type":"string"
    },
    "operatorIdentifier":{
        "type":"string"
    },
    "cardholderReceiptText":{
        "type":"string"
    },
    "acquirerReceiptText":{
        "type":"string"
    },
    "footerLines":{
        "type":"array",
        "items":{
            "line":{
                "type":"string"
            }
        }
    },
    "additionalData":{
        "type":"array",
        "items":{
            "key":{
                "type":"string"
            },
            "value":{
                "type":"dynamic"
            }
        }
    }
}

4.2.6 Payment Information Item

Field Name

Description

Type

Condition

acquirerIdentifier

The acquirer identifier for the given brand

String

Mandatory

merchantIdentifier

Merchant identifier that is used by the acquirer

String

Mandatory

acquirerTerminalIdentifier

Terminal identifier that is used by the acquirer to identify the terminal

String

Mandatory

brandIdentifer

Brand specific identifier, also known as AID. This is scheme specific e.g. A0000000041010 is Mastercard

String

Optional

brandName

The brand name like Mastercard

String (pre-defined 4.2.11 Brand Name)

Mandatory

supportedServiceTypes

Supported service types for the brand

Array (2.1.1.1 Financial Service Types)

Mandatory

cancellableServiceTypes

Service types that can be reversed

Array (2.1.1.1 Financial Service Types)

Mandatory

numberOfCancellableTransactions

Number of last (successful) transactions that can be reversed.

"-1" value shall be used if all transactions performed since last Day End can be reversed

Integer

Mandatory

supportedTechnologies

Supported technologies for card reading

Array (4.2.7 Supported Technologies)

Mandatory

supportsDCC

Whether Dynamic Currency Conversion (DCC) is supported or not

Boolean

Mandatory

supportsCashback

Whether cashback is supported or not

Boolean

Mandatory

4.2.7 Supported Technologies

Entry Mode

Description

WPI_ENTRY_MODE_MANUAL

Manual Key Entry support

WPI_ENTRY_MODE_MAGSTRIPE

Magnetic stripe support

WPI_ENTRY_MODE_CHIP

EMV chip (ICC) support

WPI_ENTRY_MODE_NFC

EMV NFC chip support

WPI_ENTRY_MODE_NFC_MIFARE

NFC MIFARE support

WPI_ENTRY_MODE_QR_CODE

Alternative payment method support, via QR Code

4.2.8 Supported Ticket Format

The supported ticket formats are defined in  4.1.1 Receipt Format.

4.2.9 Acquirer Protocol

Acquirer Protocol

ep2

CTAP

CB2A

NEXO

ZVT

MULTI-ACQUIRER

4.2.10 Authorization Mode

Authorization Mode

Description

WPI_AUTHORIZATION_MODE_ONLINE

Authorized online

WPI_AUTHORIZATION_MODE_OFFLINE

Authorized offline

4.2.11 Brand Name

Mapping should be based on Payment Application configuration returned by Acquirer. If not possible to find the right match (for e.g. brand is not specified or Payment Solution does not know what brand was used) WPI_BRAND_NAME_OTHER value shall be returned. In case of local brands, WPI_BRAND_NAME_LOCAL_DEBIT_CARD or WPI_BRAND_NAME_LOCAL_CREDIT_CARD shall be returned.

Brand Name

WPI_BRAND_NAME_MASTERCARD

WPI_BRAND_NAME_MASTERCARD_DEBIT

WPI_BRAND_NAME_MAESTRO

WPI_BRAND_NAME_VISA

WPI_BRAND_NAME_VISA_DEBIT

WPI_BRAND_NAME_VISA_ELECTRON

WPI_BRAND_NAME_VPAY

WPI_BRAND_NAME_JCB

WPI_BRAND_NAME_AMERICAN_EXPRESS

WPI_BRAND_NAME_DINERS_CLUB

WPI_BRAND_NAME_DISCOVER

WPI_BRAND_NAME_CHINA_UNIONPAY

WPI_BRAND_NAME_LOCAL_CREDIT_CARD

WPI_BRAND_NAME_GIROCARD

WPI_BRAND_NAME_CARTE_BANCAIRE

WPI_BRAND_NAME_BANCONTACT

WPI_BRAND_NAME_LOCAL_DEBIT_CARD

WPI_BRAND_NAME_ALIPAY

WPI_BRAND_NAME_WECHAT_PAY

WPI_BRAND_NAME_TWINT

WPI_BRAND_NAME_PAYCONIQ

WPI_BRAND_NAME_LOCAL_QR_CODE_BRAND

WPI_BRAND_NAME_OTHER

4.2.12 Card Data Input

Card Data Input

Description

WPI_CARD_DATA_INPUT_MANUAL_ENTRY

Card data was entered manually

WPI_CARD_DATA_INPUT_PROXIMITY_ICC

Card data was read via NFC with chip mode

WPI_CARD_DATA_INPUT_PROXIMITY_MAGNETIC_STRIPE

Card data was read via NFC with magnetic stripe mode

WPI_CARD_DATA_INPUT_ICC

Card data was read via Chip reader

WPI_CARD_DATA_INPUT_EMV_FALLBACK

Card data was read by Magnetic stripe reader due to an chip error (fallback)

WPI_CARD_DATA_INPUT_MAGNETIC_STRIPE

Card data was read through magnetic stripe reader

WPI_CARD_DATA_INPUT_ALTERNATIVE_PAYMENT_METHOD

Card data was provided through an alternative payment method (e.g. QR Code payment)

WPI_CARD_DATA_INPUT_PAN_TOKEN

Card data was provided via a tokenization service which is referencing the PAN data

WPI_CARD_DATA_INPUT_REFERENCE_BASED

Card data evaluated by the acquiring system from a previous (referenced) transaction

4.2.13 Cardholder Verification Method

Cardholder Verification Method (CVM)

Description

WPI_CVM_NO_CVM

No CVM executed

WPI_CVM_SIGNATURE

Signature CVM required

WPI_CVM_PIN_ONLINE

PIN online CVM executed

WPI_CVM_PIN_OFFLINE

PIN offline CVM executed

WPI_CVM_CD_CVM

Consumer Device CVM

WPI_CVM_PIN_ONLINE_AND_SIGNATURE

PIN online executed and signature required

WPI_CVM_PIN_OFFLINE_AND_SIGNATURE

PIN offline executed and signature required

5 Payment Solution Implementation

  1. Mandatory Attributes and Result Structure

    1. The technical design is based on defining only the mandatory attributes in the request needed to meet every requested business use case aiming to be payment protocol agnostic .

    2. The payment solution shall support every combination of attributes defined in the request.

    3. The result structure contains every possible attribute to be returned to meet every use case.

  2. Payment Solution Reference

    1. The payment solution reference must be designed in a unique way so that all follow on transactions can be handled with this. For example if you do a pre-authorization, it needs to contain all payment-specific fields to do all follow-on transactions like cancel pre-authorization, completion, and so on. WPI supports the so-called reference, for more details check Data Dictionary 4.1 Request Data, this field is also known as a merchant reference and used for reconciliation.

    2. The payment solution shall print the paymentSolutionReference on cardholder receipt in plain text or as QR Code:

      1. compliant with ISO/IEC 18004:2015 (or higher) standard.

      2. highest (H) error correction level must be ensured.

      3. QR Code version should be selected according to the length of data that given Payment Solution will return.

      4. QR Code content should be limited to paymentSolutionReference value with no additional data (i.e. raw data).

    3. The payment solution reference shall be as short as possible and easy to type manually within another Android application.

  3. Remark and Error Handling

    1. The payment solution shall provide a remark that is understandable by a third-party integrator and only in case of an error condition not equal to WPI_ERR_COND_NONE .

    2. The payment solution shall send back the errorCondition WPI_ERR_COND_BUSY in case of a transaction currently in progress.

  4. Payment Instrumentation Recognition Request

    1. In case of a Payment Instrumentation Recognition Request, the terminal shall:

      1. perform the card withdrawal in case of no amount & currency is present.

      2. not wait for another action in case of no amount & currency is present.

      3. return a token for the card PAN or the NFC UID (in case of NFC non-payment related cards) that was read. The token should be a hash which is generated by the Payment Solution and can be reproduced at least on the same device.

  5. Tip processing

    1. In case of tipAmount in the WPI request is not defined the Payment Solution has to show the tip entry screens.

    2. In case of tipAmount in the WPI request is defined >= 0 the Payment Solution will take the tip amount from the request and not show the tip entry screen

    3. In case of tipAmount is null or 0 no tip will be processed as part of given transaction

  6. Other Requirements

    1. The payment solution must store the SESSION_ID for the last transaction as well as the last transaction object of each business application. Due to this, a recovery procedure can be implemented with the last transaction request.

    2. For compatibility reasons and a certain grace period, every payment application shall support the last two major versions starting with WPI 2.0

    3. Password-protected transaction types such as refund, credit, and follow-on credit must be password protected. In case of a standalone configuration of the payment solution, password entry and validation must be done by the payment solution.

    4. The payment solution shall always take care off the receipt handling - depending on the TMS configuration. Business applications can override (deactivate) the default behavior by setting the receiptDelegation to false .