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.
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 |
|
request.port |
The socket port for making payment requests. |
10000 |
|
receipt.port |
The socket port for receiving receipts. |
20000 |
|
message.port |
The socket port for receiving status messages and dialogue requests. |
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 |
|
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 |
|
suppress.merchant.receipt |
If true, EFTLink will discard the 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 |
|
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 |
|
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. |
|
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 |
|
mid.text |
The title to display for the merchant ID in voice referrals. |
MID: |
|
tel.text |
The title to display for the telephone numbers in voice referrals. |
Tel: |
|
auth.prompt |
The text to display for the authorization code entry prompts in voice referrals. |
Enter Auth Code (or blank to cancel) |
|
max.auth.code.length |
The maximum length allowed for an entered authorization code. |
9 |
|
cashback.prompt |
The text to display for the cashback prompt. |
Cashback required? |
|
cashback.amount.prompt |
The text to display for the cashback amount prompt. |
Please enter cashback amount. |
|
min.cashback |
This is the minimum cashback amount allowed. |
Blank (no minimum amount). |
|
max.cashback |
This is the maximum cashback amount allowed. |
Blank (no maximum amount). |
|
max.cashback.length |
This is the maximum length allowed for an entered cashback amount. |
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. |
£ |
|
cnp.prompt |
This is the text to display for the customer not present 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). |
|
print.x.report |
Whether to print an X report on reconciliation. |
false |
|
print.z.report |
Whether to print a Z report on reconciliation with closure. |
false |
|
x.report.title |
The title for X reports. |
** EFT X REPORT ** |
|
z.report.title |
The title for Z reports. |
** EFT Z REPORT ** |
|
disable.cashback.prompt |
If true, then cashback will not be offered by the Point of Sale terminal. |
false |
|
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" />