WPI version 1.0

Revision #9

Table of contents

1. Overview

2. Interface Structure

3. Payment Solution Implementation

4. Data Dictionary 

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.

Revision History

• Revision #9

  • Reservation / Reservation Adjustment / Purchase Reservation

    • Chapters renamed to "Pre-authorization, "Update Pre-authorization" and "Payment Completion" respectively

    • Clarification on paymentSolutionReference usage provided

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:

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

RESPONSE

Service Types

Each intent has several service types that specify the request.

FINANCIAL

MANAGEMENT

Payment Solution Implementation

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.

• 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 field 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 Request Data , these field is also known as merchant reference and used for reconciliation.

Data Dictionary

Data

Request Data

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

Response Data

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

RESULT

ERROR CONDITIONS

ACTION CODES

RECEIPTS

Each response contains a transaction receipt for merchants and cardholders. The below example shows a pretty printed version of the JSON that the payment solution will provide - for demonstration purpose as usually each receipt content is in one line. 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.

"formattedReceipt":{
  "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"
}

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 always contains the following fields:

Purchase

Service Type: WPI_SVC_PAYMENT

Request: JSON

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

Refund

Service Type: WPI_SVC_REFUND

Request: JSON

Pre-authorization

Service Type: WPI_SVC_PRE_AUTHORIZATION

Request: JSON

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_PRE_AUTHORIZATION

Request: JSON

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

Management

Management actions has no request parameters. 

The response always contains the following fields:

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