WPI version 2.0
Revision #7
Table of contents
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.
What's new
Interface structure extension
Gather information from Payment Solution
Session support
WPI_ERR_COND_SESSION_ID_ALREADY_IN_USE
Print Receipt Session ID
Last Transaction Requests uses Session ID
WPI_VERSION changed from Integer to String
Clarified the use of messenger service for background actions
Management functional extensions:
Payment Parameterization
Acquirer Parameterization
Print Receipt
Abort Ongoing Payment
Financial extensions
Request fields added
productRecords
receiptFormat
recognitionTimeout
recognitionOptions
receiptTarget
Response fields added
dccUsed
softwareVersion
terminalIdentifier
supportedLanguages
cardholderDefaultLanguage
merchantLanguage
countryCode
defaultCurrency
supportedCurrencies
shopInfo
acquirerProtocol
supportedTicketFormats
paymentInformation
paymentSolutionSupportedServiceTypes
entryMode
isoTrack1
isoTrack2
isoTrack3
token
pan
mediaType
mediaUniqueIdentifier
waitForNextAction
nextActionWaitTime
tipAmount
Revision History
Revision#7
3. Payment Solution Implementation
Clarification added for QR Code printed on the receipt
4.1.2.5 Receipt
JSON format example updated
Revision#6
Reservation / Reservation Adjustment / Purchase Reservation
Chapters renamed to "Pre-authorization, "Update Pre-authorization" and "Payment Completion" respectively
Clarification on paymentSolutionReference usage provided
Payment Instrumentation Recognition
isoTrack1 and isoTrack2 data types changed to String in Response
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.
Android intents are used
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 .
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_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 |
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 :
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 |
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 |
Service Types
Each intent has several service types that specify the request.
FINANCIAL
Service type |
Purpose |
---|---|
WPI_SVC_PAYMENT |
Used to perform a simple sale transaction also known as purchase. |
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 reservation. |
WPI_SVC_CANCEL_PRE_AUTHORIZATION |
Used to cancel a previous reservation. |
WPI_SVC_UPDATE_PRE_AUTHORIZATION |
Used to increment a previous reservation. |
WPI_SVC_CANCEL_UPDATE_PRE_AUTHORIZATION |
Used to cancel the previous incrementation of a reservation. |
WPI_SVC_PAYMENT_COMPLETION |
Used to purchase a reservation / incremented reservation. |
WPI_SVC_CANCEL_PAYMENT_COMPLETION |
Used to cancel the purchased reservation. |
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. |
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. |
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. |
Payment Solution Implementation
Mandatory Attributes and Result Structure
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.
The payment solution shall support every combination of attributes defined in the request.
The result structure contains every possible attribute to be returned to meet every use case.
Payment Solution Reference
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 reservation, it needs to contain all payment-specific fields to do all follow-on transactions like cancel reservation, purchase reservation, and so on. WPI supports the so-called reference, for more details check Data Dictionary 4.1.1 Request Data, this field is also known as a merchant reference and used for reconciliation.
The payment solution will print the paymentSolutionReference on the receipt as QR Code:
compliant with ISO/IEC 18004:2015 (or higher) standard.
highest (H) error correction level must be ensured.
QR Code version should be selected according to the length of data that given Payment Solution will return.
QR Code content should be limited to paymentSolutionReference value with no additional data (i.e. raw data).
The payment solution reference shall be as short as possible and easy to type manually within another Android application.
Remark and Error Handling
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.
The payment solution shall send back the errorCondition WPI_ERR_COND_BUSY in case of a transaction currently in progress.
Payment Instrumentation Recognition Request
In case of a Payment Instrumentation Recognition Request, the terminal shall:
perform the card withdrawal in case of no amount & currency is present.
not wait for another action in case of no amount & currency is present.
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.
Other Requirements
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.
The payment solution should support several WPI major versions.
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.
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.
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. A payment solution for version 1.1 must remain compatible with the version 1.0.
X (Minor Version): Represents a release with new features or improvements that are backward compatible within the same major version. However, a version 2.2 request cannot be used with version 1.1.
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.
Data Dictionary
Data
All the data here below are the possible fields including the description and type for all services. As this is just a dictionary, the detailed responses per service check are listed in subsequent chapters.
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. |
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 |
productRecords |
Product catalogue for energy solution based use-cases. This records needs the format that the issuer can understand. Most often used for petrol use-cases. |
Array ( Product Record Item ) |
receiptFormat |
To override the default receipt format. |
Array ( 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 |
recognitionTimeout |
Defines the timeout before an error will be returned in milliseconds. |
Integer |
recognitionOptions |
Card recognition options. |
Array ( Recognition Option ) |
receiptTarget |
Defines the receipt which shall be printed. |
String ( Receipt Target ) |
Product Record Item
Product Records are items that will be exchanged between the integrator and the issuer. Those two parties also needs to agree on the content. The Payment Solution is just the sending the information. Example: Item ID = 55 means Carwash program "full". Each record has the following fields.
Field name |
Description |
Type |
---|---|---|
itemId |
Identifier of the item that was aligned with the issuer |
Integer |
label |
Label of the item |
String |
unitAmount |
Unit price as minor unit |
Integer |
quantity |
Number of units |
Integer |
totalAmount |
Total amount as minor unit |
Integer |
currency |
Currency of the amount. Alpha code value defined in ISO 4217 (e.g. EUR) |
String |
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) |
Purpose |
---|---|
FORMATTED |
Return the receipt in a payment response as String (default). |
JSON |
Return the receipt in a payment response as JSON. |
Recognition Option
Value (String) |
Purpose |
---|---|
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. |
Receipt Target
Value (String) |
Purpose |
---|---|
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. |
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 Result ) |
errorCondition |
Specific error reason (see table below). |
String (pre-defined Error Condition ) |
actionCode |
Specific action to be performed by the business application. |
String (pre-defined Action Code ) |
remark |
Terminal / transaction specific message for detailed error descriptions. Text provided by the acquirer and forwarded by the payment application. Content can therefore vary between acquirer and will most likely be provided in the merchant language. |
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-hhThh: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. 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, AMEX and so on. |
String |
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 ( 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 ( ShopInfo ) |
acquirerProtocol |
The used acquirer protocol by the payment solution, usually this is the official acronym like CTAP. |
String (pre-defined Acquirer Protocol ) |
supportedTicketFormats |
The supported ticket formats by the payment solution. |
String (pre-defined Receipt Format ) |
supportsReceiptDelegation |
Whether the payment application supports receipt delegation or not. Receipt delegation is when any business application asked the payment solution to handle the receipt. Any payment solution can handle the receipt if a printer or a digital solution is available. If both are not available and the payment solution cannot handle the receipt false is returned. |
Boolean |
paymentInformation |
Detailed payment solution information per brand & acquirer. |
Array ( 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 ( Financial Service Types & Management Service Types ) |
entryMode |
The technology that was used to read the card. |
String (pre-defined Supported Technologies ) |
isoTrack1 |
ISO track 1 data |
String |
isoTrack2 |
ISO track 2 data (due to PCI regulatory payment card PAN data are always masked) |
String |
isoTrack3 |
ISO track 3 data |
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). |
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 |
ShopInfo
Field name |
Description |
Type |
---|---|---|
name |
Name of the shop. |
String |
address |
Address of the shop usually street and number. |
String |
zipCode |
ZIP code of the shop. |
String |
city |
City of the shop. |
String |
country |
Country of the ship. |
String |
logo |
Content provider URI of the logo to be used. |
String |
RESULT
Result |
Description |
---|---|
WPI_RESULT_SUCCESS |
In case of successful transaction. |
WPI_RESULT_FAILURE |
In case of failed transaction. |
ERROR CONDITIONS
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 |
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. |
ACTION CODES
Action codes |
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. |
RECEIPTS
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"
},
"productRecords":{
"type":"array",
"items":{
"itemId":{
"type":"integer"
},
"label":{
"type":"string"
},
"unitAmount":{
"type":"integer"
},
"quantity":{
"type":"integer"
},
"totalAmount":{
"type":"integer"
},
"currency":{
"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"
}
}
}
}
PAYMENT INFORMATION ITEM
Field name |
Description |
Type |
---|---|---|
acquirerIdentifier |
The acquirer identifier for the given brand. |
String |
merchantIdentifier |
Merchant identifier that is used by the acquirer. |
String |
acquirerTerminalIdentifier |
Terminal identifier that is used by the acquirer to identify the terminal. |
String |
brandIdentifer |
Brand specific identifier, also known as AID. This is scheme specific e.g. A0000000041010 is Mastercard. |
String |
brandName |
The brand name like Mastercard |
String |
supportedServiceTypes |
Supported service types for the brand |
Array ( Financial Service Types ) |
cancellableServiceTypes |
Service types that can be reversed |
Array ( Financial Service Types ) |
numberOfCancellableTransactions |
Number of last (successful) transactions that can be reversed. |
Integer |
supportedTechnologies |
Supported technologies for card reading |
Array ( Supported Technologies ) |
supportsDCC |
Whether Dynamic Currency Conversion (DCC) is supported or not |
Boolean |
SUPPORTED TECHNOLOGIES
Entry mode |
Description |
---|---|
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 |
SUPPORTED TICKET FORMAT
The supported ticket formats are defined in Receipt Format
ACQUIRER PROTOCOL
Acquirer protocol |
---|
ep2 |
CTAP |
CB2A |
NEXO |
ZVT |
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 |
remark |
String |
Conditional - only for not successful transactions |
actionCode |
String |
Conditional - only for not successful transactions |
timestamp |
String (ISO 8601) |
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 |
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 ( Receipt ) |
Conditional - always present for successful transactions - optional for failed transactions |
paymentSolutionReference |
String |
Conditional - always present for successful transactions - optional for failed transactions |
productRecords |
Array |
Conditional - in case of the product records are present in the request |
Payment
Service Type : WPI_SVC_PAYMENT
Request
:
Field name |
Type |
Condition |
---|---|---|
currency |
String |
Mandatory |
requestedAmount |
Integer |
Mandatory |
reference |
String |
Optional |
productRecords |
Array |
Optional - usually used for energy solutions (e.g. petrol retail). |
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 |
Refund
Service Type : WPI_SVC_REFUND
Request
:
Field name |
Type |
Condition |
---|---|---|
currency |
String |
Mandatory |
requestedAmount |
Integer |
Mandatory |
reference |
String |
Optional |
Pre-authorization
Service Type : WPI_SVC_PRE_AUTHORIZATION
Request
:
Field name |
Type |
Condition |
---|---|---|
currency |
String |
Mandatory |
requestedAmount |
Integer |
Mandatory |
reference |
String |
Optional |
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 |
Confition |
---|---|---|
currency |
String |
Mandatory |
requestedAmount |
Integer |
Mandatory |
paymentSolutionReference |
String |
Mandatory |
reference |
String |
Optional |
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 |
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.
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.
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.
AUTHORIZATION
Service Type : WPI_SVC_DEFERRED_PAYMENT_AUTHORIZATION
Request
:
Field Name |
Type |
Condition |
---|---|---|
currency |
String |
Mandatory |
requestedAmount |
Integer |
Mandatory |
reference |
String |
Optional |
Service Type : WPI_SVC_DEFERRED_PAYMENT_COMPLETION
Request
:
Field Name |
Type |
Condition |
---|---|---|
currency |
String |
Mandatory |
requestedAmount |
Integer |
Mandatory |
paymentSolutionReference |
String |
Mandatory |
reference |
String |
Optional |
productRecords |
Array |
Optional |
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
|
requestedAmount |
Integer |
Optional
|
serviceType |
String |
Optional
|
recognitionTimeout |
Integer |
Mandatory |
recognitionOptions |
Array |
Mandatory |
Response
:
Field Name |
Type |
Condition |
---|---|---|
result |
String |
Mandatory |
errorCondition |
String |
Mandatory |
entryMode |
String |
Conditional
|
customerLanguage |
String |
Conditional
|
isoTrack1 |
String |
Conditional
|
isoTrack2 |
String |
Conditional
|
isoTrack3 |
String |
Conditional
|
token |
String |
Conditional
|
pan |
String |
Conditional
|
mediaType |
String |
Conditional
|
mediaUniqueIdentifier |
String |
Conditional
|
waitForNextAction |
Boolean |
Conditional
|
nextActionWaitTime |
Integer |
Conditional
|
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. The reference of the card is given by the paymentSolutionReference of the previous 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 |
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 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 response for every management action contains the following fields
Response
:
Field Name |
Type |
Condition |
---|---|---|
result |
String |
Mandatory |
errorCondition |
String |
Mandatory |
receipt |
Object ( Receipt ) |
Conditional
|
Payment Menu
This is used to open the payment solution menu to trigger payment solution specific actions.
Service Type : WPI_SVC_PAYMENT_MENU
Day-End
The day-end is used to upload the offline transactions to the host and sends back a receipt with the transaction summary per brand with no of transactions as well as the full amount since the last day-end.
Service Type : WPI_SVC_DAY_END
Payment Parameterization
The payment configuration is used to synchronize the payment solution specific parameters with the corresponding management system.
Service Type : WPI_SVC_PAYMENT_PARAMETERIZATION
Acquirer Parameterization
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
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 transaction was done and due to this the payment solution has a last transaction 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 |
ErrorCondition |
---|---|---|
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 Payment Solution Information |
WPI_ERR_COND_SERVICE_NOT_SUPPORTED |
Receipt not available |
Not every WPI request has receipt´s or a receipt of the requested receiptTarget . For example a configuration receipt cannot be printed with the receiptTarget CARDHOLDER as this is a merchant receipt. |
WPI_ERR_COND_GENERIC |
Service Type : WPI_SVC_PRINT_RECEIPT
Request
:
Field Name |
Type |
Condition |
---|---|---|
receiptTarget |
String (pre-defined ) |
Mandatory |
Response
:
Field Name |
Type |
Condition |
---|---|---|
result |
String (pre-defined ) |
Mandatory |
errorCondition |
String (pre-defined ) |
Mandatory |
remark |
String |
Conditional
|
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
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.
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 |
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 |
Type |
Condition |
---|---|---|
result |
String |
Mandatory |
errorCondition |
String |
Mandatory |
softwareVersion |
String |
Conditional
|
terminalIdentifier |
String |
Conditional
|
terminalModel |
String |
Conditional
|
macAddress |
String |
Conditional
|
supportedLanguages |
Array |
Conditional
|
cardholderDefaultLanguage |
String |
Conditional
|
merchantLanguage |
String |
Conditional
|
countryCode |
String |
Conditional
|
defaultCurrency |
String |
Conditional
|
supportedCurrencies |
Array |
Conditional
|
shopInfo |
Object ( ShopInfo ) |
Conditional
|
acquirerProtocol |
String |
Conditional
|
supportedTicketFormats |
Array |
Conditional
|
supportReceiptDelegation |
Boolean |
Conditional
|
paymentInformation |
Array |
Conditional
|
paymentSolutionSupportedServiceTypes |
Array |
Conditional
|