1. Core Configuration Guide
  2. WorldPay

13 WorldPay

This chapter covers EFTLink Integration with WorldPay Payment Systems. It should be read in conjunction with the Oracle Retail EFTLink Framework Installation and Configuration Guide.

EFTLink General

This document assumes static EFTLink configuration. When deploying with a POS that supports dynamic configuration, all property settings referred to below should be set on the POS, and not directly into local property files.

Minimum Version

The WorldPay interface requires a minimum EFTLink version of 20.0.

System Architecture

EFTLink connects to the WorldPay application that is installed on the same PC as the POS, using a proprietary socket protocol. The WorldPay application must be started.

Note:

This document does not cover the install of the WorldPay software.

Fileset

The following files are used in the EFTLink folder:

cores/WorldPay/worldpaycore.jar

worldpay.properties (optional, if not present defaults apply)

Language

There are no translation files in worldpaycore.jar. EFTLink Framework should be set to default English. See the Oracle Retail EFTLink Framework Installation and Configuration Guide, EFTLink General Information, Translation section:

EftlinkConfig.properties

DisplayLanguage = EN

Core Classname

The following should have been set in the EftlinkConfig.properties file by installcore.bat or installcore.sh:

EPSCore0 = manito.eft.worldpay.WorldPayCore

Configuration Settings

The core is configured via settings inserted into the worldpay.properties file located in the chosen EFTLink folder. If the default port numbers are used within WorldPay's software configuration then this file does not need to be present as the core will work without it. The available settings are listed below.

Note:

The software was previously called YesPay.

Table 13-1 WorldPay - Configuration Settings

Setting Description Default Example

yeseft.folder

The path to the folder where the WorldPay software is installed. Worldpay is normally installed in a folder at the root of the C: drive of the PC called YESEFT.

\YESEFT

yeseft.folder = \YESEFT

request.port

The socket port for making payment requests.

10000

request.port = 10000

receipt.port

The socket port for receiving receipts.

20000

receipt.port = 20000

message.port

The socket port for receiving status messages and dialogue requests.

8000

message.port = 8000

perform.card.range.lookup

If true, EFTLink will use its mapping file CardRange.xml to determine the card scheme name based on information returned by WorldPay. Otherwise, it will return the text provided by WorldPay.

false

perform.card.range.lookup = false

embed.customer.receipt

If true, EFTLink will return the customer receipt to the POS to be included in its own receipt rather than printing it separately.

Note: Not all POS systems may support this feature.

false

embed.customer.receipt = false

suppress.merchant.receipt

If true, EFTLink will discard the merchant receipt.

false

suppress.merchant.receipt = false

store.merchant.receipt

If true, EFTLink will return the merchant receipt to the POS to be added to the electronic journal rather than printing it separately. This setting is overridden by suppress.merchant.receipt.

Note: Not all POS systems may support this feature.

false

store.merchant.receipt = false

language

The language code for translating responses from WorldPay on the message port.

The translations are taken from WorldPay files in the WorldPay folder. The default value is "en_GB", and references part of the filename provided by WorldPay. JVTMessageBundle_en_GB.properties in \YESEFT\properties folder.

en_GB

language = en_GB

signature.reprint.prompt

The text to display when asking if a signature receipt should be reprinted. This text will only be shown if the operator answers no, when asked to confirm signature ok for a previous print.

Blank, meaning reprint will not be offered.

signature.reprint.prompt =

notify.signature.print

If true, the POS will be notified that a signature receipt has been printed. This is for the business case where the signed receipt must be stored in the cash drawer and therefore the POS needs to know to open the drawer.

Note: An additional setting is required in EftlinkConfig.properties to enable this function: DeviceEvents=true

true

notify.signature.print = true

mid.text

The title to display for the merchant ID in voice referrals.

MID:

mid.txt = MID:

tel.text

The title to display for the telephone numbers in voice referrals.

Tel:

tel.txt = Tel:

auth.prompt

The text to display for the authorization code entry prompts in voice referrals.

Enter Auth Code (or blank to cancel)

auth.prompt = Enter Auth Code (or blank to cancel)

max.auth.code.length

The maximum length allowed for an entered authorization code.

9

max.auth.code.length = 9

cashback.prompt

The text to display for the cashback prompt.

Cashback required?

cashback.prompt = Cashback required?

cashback.amount.prompt

The text to display for the cashback amount prompt.

Please enter cashback amount.

cashback.amount.prompt = Please enter cashback amount

min.cashback

This is the minimum cashback amount allowed.

Blank (no minimum amount).

min.cashback =

max.cashback

This is the maximum cashback amount allowed.

Blank (no maximum amount).

max.cashback = 100

max.cashback.length

This is the maximum length allowed for an entered cashback amount.

5

max.cashback.length = 5

currency.symbol

The currency symbol to use when displaying cashback limits to the operator. This can be any text required, for example "GBP" and so on.

£

currency.symbol = £

cnp.prompt

This is the text to display for the customer not present prompt.

CNP confirmation

cnp.prompt = CNP confirmation

response.timeout

The timeout in milliseconds to wait for a response from WorldPay after sending a request. It is recommended that this be left disabled (indefinite) and leave the timeout to WorldPay.

0 (indefinite).

response.timeout = 0

print.x.report

Whether to print an X report on reconciliation.

false

print.x.report = false

print.z.report

Whether to print a Z report on reconciliation with closure.

false

print.z.report = false

x.report.title

The title for X reports.

** EFT X REPORT **

x.report.title=** EFT X REPORT **

z.report.title

The title for Z reports.

** EFT Z REPORT **

z.report.title=** EFT Z REPORT **

disable.cashback.prompt

If true, then cashback will not be offered by the Point of Sale terminal.

false

disable.cashback.prompt = true

Supported Functions

Below is a list of supported functionalities of the interface to WorldPay

Table 13-2 WorldPay - Supported Functions

Function Description

Payment

Sends payment request to WorldPay application. The client will return a response message with formatted receipt strings for customer and/or merchant receipts.

Appropriate receipts will be printed at the end of transaction.

Cashback

If the WorldPay client (IPC) is enabled for cashback then EFTLink will prompt the associate if cashback is required. EFTLink can suppress the cashback request by enabling the property "disable.cashback.prompt" in the core properties file.

In addition, the offering of cashback can also be suppressed via the CardServiceRequest.

If suppress.cashback=true is added to the MiscellaneousData element then cashback will be suppressed.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<CardServiceRequest RequestType="CardPayment" ApplicationSender="XSTORE" WorkstationID="1" RequestID="3">
 <POSdata LanguageCode="eng">
  <POSTimeStamp>2020-01-14T11:33:39</POSTimeStamp>
  <TransactionNumber>39</TransactionNumber>
  <StoreID>101</StoreID>
 </POSdata>
    <MiscellaneousData>suppress.cashback=true</MiscellaneousData>
 <TotalAmount Currency="USD">10.00</TotalAmount>
 <SaleItem ItemID="_1">
 <ProductCode>0</ProductCode>
 <Department>NP</Department>
 <Amount OriginalAmount="10.00">10.00</Amount>
 <UnitPrice>10.00</UnitPrice>
 <Quantity>1</Quantity>
 <TaxCode>0</TaxCode>
 <TaxRate>0.00</TaxRate>
 <AdditionalProductCode>1026</AdditionalProductCode>
 <AdditionalProductInfo>Non Phys   Item</AdditionalProductInfo>
 </SaleItem>
 <PaymentProviderName />
</CardServiceRequest>

Reversal

Reversal requests require the card payment reference, PAN and card expiry date from the original transaction. Additionally, a reversal should carry the same transaction number as the transaction it is cancelling. Below is an example reversal request with the necessary data fields highlighted.

<?xml version="1.0" encoding="UTF-8"?>
<CardServiceRequest RequestType="PaymentReversal" ApplicationSender="POSSIM" WorkstationID="1" RequestID="9" RequestSubType="OperatorReversal">
  <POSdata LanguageCode="en">
    <POSTimeStamp>2015-06-09T11:48:29</POSTimeStamp>
    <TransactionNumber>401</TransactionNumber>
  </POSdata>
  <OriginalTransaction TerminalID="22980092" STAN="401" TimeStamp="2015-06-09T11:48:27" RequestType="CardPaymentLoyaltyAward" ApprovalCode="956872" MiscellaneousData="{Status=ONLINE}" />
  <TotalAmount Currency="GBP">15.00</TotalAmount>
  <CardValue CardType="3" Tender="0108" LoyaltyEligible="true">
    <CardPAN>476173******0119</CardPAN>
    <EndDate>1263</EndDate>
    <CardCircuit>VISA CREDIT</CardCircuit>
    <Hash>52FDA2337F840BEE654353EA1D1F54FB5EFC2E98</Hash>
    <Token>533173099D9A95649</Token>
    <TransactionReference>PGTR327632569</TransactionReference>
  </CardValue>
</CardServiceRequest>

Refund

Sends refund requests to the WorldPay application. The client will refund a transaction with specified amount.

Tokenized Refund

To perform refunds via token both the token and the card payment reference from the original sale must be provided in the refund request, please see below for an example of a payment response from EFTLink showing these fields.

<?xml version="1.0" encoding="UTF-8"?>
<CardServiceResponse RequestType="CardPaymentLoyaltyAward" ApplicationSender="POSSIM" WorkstationID="1" RequestID="4" OverallResult="Success">
  <Terminal TerminalID="22980092" DeviceID="0081226814" MerchantID="6818780" STAN="345" />
  <Tender>
    <TotalAmount Currency="GBP">56.00</TotalAmount>
    <Authorization AcquirerID="UNKNOWN" TimeStamp="2015-04-29T12:45:31" ApprovalCode="947265" CardType="3" Tender="0108" CardPAN="476173******0119" ExpiryDate="1251" CardCircuit="VISA CREDIT" TransactionReference="PGTR740971038" />
  </Tender>
  <CardValue CardType="3" Tender="0108" LoyaltyEligible="true">
    <CardPAN>476173******0119</CardPAN>
    <EndDate>1251</EndDate>
    <CardCircuit>VISA CREDIT</CardCircuit>
    <Hash>1CCF57529637C314FBE9C6544BF10E3D16FE20B8</Hash>
    <Token>533173099D9A95649</Token>
    <TransactionReference>PGTR740971038</TransactionReference>
  </CardValue>
  <MiscellaneousData>{Status=ONLINE}</MiscellaneousData>
</CardServiceResponse>
Below is an example of a subsequent refund request from the POS.
<?xml version="1.0" encoding=" UTF-8"?>
<CardServiceRequest RequestType="PaymentRefund" ApplicationSender=" POSSIM " WorkstationID="1" RequestID="5">
  <POSdata LanguageCode="en" SpooledPrint="false">
    <POSTimeStamp>2015-04-29T12:46:31</POSTimeStamp>
    <TransactionNumber>920</TransactionNumber>
  </POSdata>
  <TotalAmount Currency="GBP">56.00</TotalAmount>
  <CardValue>
    <Token>533173099D9A95649</Token>
    <TransactionReference> PGTR740971038</TransactionReference>
  </CardValue>
</CardServiceRequest>

X reports (reconciliation)

Offers the ability to print a reconciliation report.

This is an online function only. If the network is not available then the transaction will be cancelled, and no report data will be returned in response.

Z reports (reconciliation with closure)

Offer the ability to print a reconciliation with closure report.

This is an online function only, If the network is not available then the transaction will be cancelled, and no report data will be returned in response.

Integration Notes

This section describes key points for the WorldPay integration.

WorldPay Configuration

The WorldPay software must be configured to use its socket interface on all three ports (request, receipt and message) respectively. Within the WorldPay (YESEFT) configuration utility the relevant tabs are Interfacing, Receipt and Hosted IPC.

Online/Offline Indication

In a card payment response, the miscellaneous data field will indicate whether the authorization was online, offline or manual (voice referral). The format will be {Status=xxx} where xxx is one of ONLINE, OFFLINE or MANUAL.

Device ID

The terminal number will be returned in the Device ID element of the EFTLink login response (if the WorldPay software is running at the point of login) and with each card payment response thereafter. An example login response is provided below.

<?xml version="1.0" encoding="UTF-8"?>
<ServiceResponse RequestType="Login" ApplicationSender="POSSIM" WorkstationID="1" RequestID="2" OverallResult="Success">
  <Terminal DeviceID="12345678" />
</ServiceResponse>

Note:

The Terminal Device ID should be the pertinent one for the terminal being connected.

Signature Print Notification

If the core is configured to notify the POS of a signature print (see section 0) then a device event will be generated as shown below. The POS should examine the Event Type field to determine that this is a signature print notification.

<?xml version="1.0" encoding="UTF-8"?>
<DeviceRequest ApplicationSender="MICROS" WorkstationID="1" RequestID="5.11" RequestType="Event">
  <Event Event Type="SIGNATURE" />
</DeviceRequest>

The POS should acknowledge the device event as in the following example.

<?xml version="1.0" encoding="UTF-8"?>
<DeviceResponse RequestType="Event" ApplicationSender="MICROS" WorkstationID="1" RequestID="5.11" OverallResult="Success" />