How-to Guide - Configuring NFC Loyalty

---

Introduction

The Enactor NFC Loyalty configuration enables four distinct features that together deliver a streamlined, NFC-based loyalty capture experience at the POS:

• NFC Single TAP Loyalty - customers present their digital loyalty card stored in Apple Wallet or Google Wallet to a PED (Payment Entry Device) via NFC. The PED reads the card details in a single tap using the VAS (Value Added Services) protocol, eliminating the need for a separate card scan or barcode.
• Automatic Loyalty Capture - the PED is armed for NFC VAS loyalty capture automatically when the POS is at the selling prompt, removing the need for the operator to press a button manually.
• Employee Sales - when an employee sale is triggered by the POS operator, the PDC enables VAS NFC capture at the PED. The captured pass card number is propagated back to the POS and used to look up the employee by card number.
• Custom PED Displays - merchant-branded HTML screens are shown on the PED to indicate whether it is armed for loyalty capture, payment capture, or both.

The purpose of this guide is to demonstrate the steps required to configure all four of these NFC Loyalty features on Enactor, covering ICC Reader VAS resource files, PED display setup, PDC reconfiguration, and POS process and privilege configuration.

note

The physical NFC key loading onto each PED (KBPK VRK injection) is performed by Smart Payment Technologies and must be completed before this configuration is applied. See the Appendix for details on the key loading process.

---

Overview

The following steps are required to enable NFC Single TAP Loyalty:

1. Digital Wallet Configuration - Configure Apple Wallet or Google Wallet with loyalty and payment support (refer to Apple/Google and card issuer documentation)
2. PDC Configuration - Add VAS resource files to the ICC Reader Configuration, configure PED display HTML and images, and deploy to the PDC
3. POS Configuration - Create process details, configure the Payment Service/Loyalty button, set user role privileges, create the NFC loyalty attribute option set, assign values per terminal, and configure the Application Event Queue for automatic capture
4. Broadcasting - Deliver the updated configuration to the POS

Prerequisites

Before starting, you should have the following in place:

• Enactor Estate Manager
• Enactor POS with PDC and PED hardware commissioned and connected
• NFC Loyalty key loading completed on each PED by Smart Payment Technologies
• An existing ICC Reader Configuration record for the target PED

You should be familiar with the following:

• Estate Manager configuration
• ICC Reader Configuration Maintenance
• Process Detail Maintenance
• Data broadcasting

In addition, note the following requirements:

• Ensure employee card data is entered into the Employee Card Maintenance module whenever a card number differs from the employee number.
• The currency code comes from CONTLEMV.CFG (e.g. the 5F2A = 0826 line -> GBP).
• Keep the VIPA DisplayHints setting at its default (1 / enabled) in CICAPP.CFG
• Ensure the required NFC Loyalty keys are loaded onto the PED before proceeding.
• Required VIPA version 6.8.2.33

Limitation

1. One merchant Config Per PED
2. Setup is one PDC/PED pair per POS terminal

---

Configuration Steps - Digital Wallet Configuration

NFC Single TAP flows can be configured to support both loyalty cards and payment cards stored in Apple Wallet or Google Wallet. The setup differs depending on the wallet platform and the card type being provisioned.

info

Refer to the official documentation provided by Apple and Google, as well as the specific card issuer or loyalty programme provider, to ensure the correct wallet configuration is applied. This step is performed outside of the Enactor Estate Manager.

This completes the Digital Wallet configuration.

---

Configuration Steps - PDC Configuration

PDC Configuration covers three areas: adding the required VAS resource files to the ICC Reader Configuration, configuring the PED display, and deploying the changes to the PDC.

ICC Reader Configuration - Add Required Resource Files

The ICC Reader Configuration must be updated to include the VAS configuration files that instruct the PED to handle Apple Pay and Google Pay loyalty cards presented via NFC.

Navigate to ICC Reader Configuration Maintenance using the path:

Configuration > Organisation > ICC Reader Configurations

Edit the appropriate configuration record. Open the Resources tab.

Add each of the following files. For each file, set the Deployment Path to the exact filename as shown:

Resource Name	Deployment Path	Resource Type
wallet_vas_config.json	wallet_vas_config.json	UNKNOWN
terminal_vas_config.json	terminal_vas_config.json	UNKNOWN
<XXXX>.wky	flash/<XXXX>.wky	UNKNOWN

note

The filenames must be entered exactly as shown (case-sensitive). Incorrect filenames will prevent VAS card support from activating.

The following screenshot shows the VAS JSON configuration files added to the Resources tab, highlighted for reference:

The Resources tab must include both terminal_vas_config.json and wallet_vas_config.json. The Deployment Path for each must match the filename exactly. These files instruct the PED to process VAS loyalty cards from Apple Wallet and Google Wallet.

The following screenshot shows the .wky key file added to the Resources tab:

Field	Value
Resource Name	<XXXX>.wky (your merchant-specific key filename)
Resource Type	UNKNOWN
Deployment Path	flash/<XXXX>.wky

Add the .wky key file to the Resources tab. Set the Deployment Path to flash/<filename>.wky. The Resource type will show as UNKNOWN - this is expected for binary key files.

Next, navigate to the Contactless tab and enable contactless loyalty card support:

Field	Value
Enable Contactless	Checked
Enable Contactless Loyalty Cards	Checked

On the Contactless tab, tick Enable Contactless Loyalty Cards to activate NFC VAS loyalty capture on this ICC Reader configuration. Enable Contactless must also be ticked.

Select Save to save the configuration.

This completes the ICC Reader Resource Files configuration.

---

PED Display Configuration

The PED displays custom HTML screens to the cardholder to indicate whether it is armed for loyalty capture, payment capture, or both. Three resources must be configured: the HTML hint file and the display images.

Upload ctls_hint_6.html

Upload ctls_hint_6.html to the PED at I:15:/www/mapp/ctls_hint_6.html via the Resources tab.

Download ctls_hint_6.html

On the Resources tab of ICC Reader Configuration Maintenance, add the following entry:

Resource Name	Deployment Path	Resource Type
ctls_hint_6.html	I:15:/www/mapp/ctls_hint_6.html	HTML_DOCUMENT

Add ctls_hint_6.html with Resource type set to HTML_DOCUMENT and Deployment Path set to I:15:/www/mapp/ctls_hint_6.html. This file controls the PED contactless hint screen layout.

Upload PED Display Image Files

Add the following image files to the Resources tab. The filenames must match exactly - these are referenced by the HTML hint file to display the correct image for each capture mode:

Resource Name	Deployment Path	Resource Type	Purpose
loyalty.png	I:15:/www/loyalty.png	PNG_IMAGE	Loyalty capture only
payment.png	I:15:/www/payment.png	PNG_IMAGE	Payment capture only
paymentloyalty.png	I:15:/www/paymentloyalty.png	PNG_IMAGE	Payment and Loyalty (Single TAP)

Add loyalty.png with the exact Deployment Path shown. This image is displayed on the PED when it is armed for NFC loyalty capture only.

Add payment.png and paymentloyalty.png with the exact Deployment Paths shown. These images are displayed on the PED for payment-only and combined payment-and-loyalty (Single TAP) modes respectively.

tip

Any suitable PNG image may be substituted, but the filename must match exactly as shown above.

Test images are available in the following zip file:

Download PED-Display-Test-Images.zip

Configure PED Custom Display Captions

Navigate to the General tab in ICC Reader Configuration Maintenance.

Enable Enable Ped Custom Display and set the caption fields as appropriate for your merchant branding:

Field	Example Value
Enable Ped Custom Display	Checked
Payment and Loyalty Caption	NFC Payment and loyalty card
Payment Caption	Present Card
Loyalty Caption	Present loyalty

On the General tab, tick Enable Ped Custom Display and complete the three caption fields. These captions control the text displayed on the PED screen for each capture mode.

Select Save to save the configuration.

This completes the PED Display configuration.

---

Re-Configuration to the PDC

After saving the ICC Reader Configuration, deploy the updated configuration to the PDC.

Navigate to Payment Device Host Status Maintenance using the path:

Configuration > Financial > Payment Device Host Status

Select the relevant PDC record.

Open the Pending Commands tab. Add the following commands and save:

• Reconfigure payment device host
• Restart payment device host

Add both Reconfigure payment device host and Restart payment device host to the Pending Commands tab, then save. The PDC and PED will restart and apply the updated ICC Reader Configuration including the VAS resource files.

This completes the PDC Re-Configuration.

---

Configuration Steps - POS Configuration

POS Configuration covers the process details, menu button, user role privileges, terminal attribute option set, and Application Event Queue setup required to enable NFC loyalty capture at the POS.

Enable Loyalty Capture Process at the POS

To enable loyalty card capture via the PDC at the POS, a new entry must be created in Process Detail Maintenance.

Navigate to Process Details using the path:

Configuration > System > Process Details

Create a new Process Detail with the following values on the General tab:

Field	Value
Process Detail ID	Pos/Loyalty/SelectPdcLoyaltyCardCapture
Process Type	Process
Process ID	Pos/Loyalty/SelectPdcLoyaltyCardCapture

Create a new Process Detail with Process Type set to Process and Process ID set to Pos/Loyalty/SelectPdcLoyaltyCardCapture. No process file upload is required - the configuration alone is sufficient to register the extension point.

Open the Extension tab and configure the Extension Point:

Field	Value
Extension Point	SelectLoyaltyCardCaptureMethod

On the Extension tab, set the Extension Point to SelectLoyaltyCardCaptureMethod. This registers the PDC loyalty capture method as the active loyalty card capture handler at the POS.

Select Save to save the process detail.

This completes the Loyalty Capture Process configuration.

---

Configure the Payment Service/Loyalty Button

A new menu button must be configured at the POS to allow operators to trigger the combined payment and loyalty capture mode.

Navigate to Menus using the path:

Configuration > System > Menus

Select the relevant Tender Menu from the list.

Copy an existing Payment Service button and rename the button text to Payment Service/Loyalty.

Open the Data tab and add the following key-value entries:

Name	Java Type	Value
enactor.mfc.TenderId	String	PAYMENT_SERVICE
enactor.pos.PaymentMode	String	PAYMENT_LOYALTY

On the Data tab, add both key-value pairs exactly as shown. The enactor.mfc.TenderId value identifies the tender type and enactor.pos.PaymentMode sets the mode to combined payment and loyalty capture.

Select Save to save the menu button.

This completes the Payment Service/Loyalty button configuration.

---

Set Privileges

The following privileges must be enabled in User Role Maintenance for the relevant POS user roles to permit use of the Payment Service/Loyalty tender mode.

Navigate to User Roles using the path:

Configuration > HR > User Roles

Select the relevant POS User Role.

Open the Authorised Functions tab. Filter by:

• Application Package: Enactor POS
• Process: # Payment Service Payment Tender

Enable the following privileges:

Privilege	Description
enactor.pos.PaymentServiceTenderPaymentLoyaltyModeAllowed	Allows the operator to use the Payment Service/Loyalty tender mode
enactor.pos.AuthorisesPaymentServiceTenderPaymentLoyaltyMode	Authorises the operator to activate the Payment Service/Loyalty mode

Enable PaymentServiceTenderPaymentLoyaltyModeAllowed and AuthorisesPaymentServiceTenderPaymentLoyaltyMode for the relevant POS User Role. Without these privileges, operators cannot access or authorise the Payment Service/Loyalty button.

Select Save to save the user role.

This completes the Privilege configuration.

---

Create the NFC Loyalty Attribute Option Set

An Attribute / Option Set must be created (or extended) to hold the NFC loyalty configuration options that are assigned per POS terminal.

Navigate to Attribute / Option Sets using the path:

Configuration > Merchandise > Attribute / Option Sets

Create a new Option Set (or add to an existing NFC loyalty-related set) with the following settings:

Field	Value
Attribute / Option Set ID	NFC_LOYALTY_CONFIG
Type	POS Terminal Attributes
Region	Select the appropriate region

Within the Option Set, add the following options:

Option ID	Choice Type	Name	Description
autoEnableNfcLoyalty	Boolean	Auto Enable NFC Loyalty	When true, the POS automatically arms the PED for NFC VAS loyalty capture on transaction start
employeeSearchVasCapture	Boolean	Employee VAS search	When true, the POS automatically arms the PED for NFC VAS to capture the employee card during an employee sale

Select Save to save the Option Set.

This completes the NFC Loyalty Attribute Option Set configuration.

---

Assign Values per POS Terminal

The NFC loyalty options must be assigned to each POS terminal individually, or via a POS Terminal Template for bulk configuration.

Navigate to POS Terminals using the path:

Configuration > Organisation > POS Terminals

(Or use POS Terminal Template Maintenance for bulk configuration.) Edit the relevant terminal.

Open the Attributes tab. Locate the NFC_LOYALTY_CONFIG option set. For each option, uncheck Discard Value and set the value as required:

Option	Value	Effect
autoEnableNfcLoyalty	true	POS automatically arms the PED for NFC loyalty capture on transaction start
employeeSearchVasCapture	true	POS automatically arms the PED for NFC VAS to capture the employee card during employee sales

Select Save and then broadcast the POS Terminal entity.

This completes the POS Terminal attribute assignment.

---

Application Event Queue - Startup Configuration

To support automatic loyalty capture, the Application Event Queue must be started at POS startup. Create a Process Detail to register the queue at startup.

Navigate to Configuration > System > Process Details in the Estate Manager.

Create a new Process Detail with the following values on the General tab:

Field	Value
Process Detail ID	StartApplicationEventQueue
Process Type	Process
Process ID	Pos/ApplicationEventQueue/StartApplicationEventQueue

Open the Extension tab and configure the following:

Field	Value
Extension Point	StartupExtension

Select Save to save the process detail.

This completes the Startup Configuration.

---

Application Event Queue - Initialise Queue Reader and Writer

A second Process Detail is required to initialise the queue reader and writer when the POS operator signs on.

Navigate to Configuration > System > Process Details in the Estate Manager.

Create a new Process Detail with the following values on the General tab:

Field	Value
Process Detail ID	InitialiseApplicationQueue
Process Type	Process
Process ID	Pos/ApplicationEventQueue/RetrieveApplicationQueueHandles

Open the Extension tab and configure the following:

Field	Value
Extension Point	SignedOnExtension

Select Save to save the process detail.

This completes the Queue Initialisation configuration.

---

Configuration Steps - Broadcasting

To deliver the configuration changes to the POS, broadcast the following entities:

• ICC Reader Configuration - deploys VAS resource files and PED display files to the PDC/PED
• Process Details - registers loyalty capture and event queue processes at the POS
• Menu Configuration - deploys the Payment Service/Loyalty button
• User Roles - applies the updated privilege set
• POS Terminal - applies the NFC_LOYALTY_CONFIG attribute values

After the POS restarts, it will use the configured process extension points to enable the PED for NFC loyalty card capture automatically when available.

This completes the Broadcasting configuration.

---

Rollback - PED Display

note

This section is only required if you need to revert to the default contactless UI. If you are not rolling back, skip this section.

The custom ctls_hint_6.html replaces the default contactless UI (present_card.html). To revert to the default:

1. Navigate to ICC Reader Configuration Maintenance and open the General tab.
2. Disable Enable Ped Custom Display.

Untick Enable Ped Custom Display on the General tab. The caption fields will become greyed out, indicating the custom PED display is disabled.

3. Navigate to the Resources tab and delete the existing ctls_hint_6.html entry.

4. Upload a new file to the exact same location, keeping the exact same file name (ctls_hint_6.html). Important: Only the content changes - ensure the inside of this file contains the present_card.html content.

   Download ctls_hint_6.html

5. Remove loyalty.png, paymentloyalty.png, and payment.png from the Resources tab.

6. Select Save, then reconfigure and restart the PDC and PED using Payment Device Host Status Maintenance.

This completes the Rollback procedure.

---

Appendix - PED Key Load (KBPK VRK)

note

If the PED key loading has already been completed, skip this section.

Each PED must be loaded with a Kbpk (Key Block Protection Key) so that it can decrypt and use the VAS ECC private key from the .wky file. The Kbpk is managed by Verifone on behalf of the merchant.

The Kbpk is distributed and loaded onto a PED in the form of a PED-specific VRK (Verifone Remote Key) package, signed by Verifone and encrypted under the public key of the target PED. The Kbpk is loaded onto each PED when commissioned by Smart Payment Technologies.

Abbreviations

Abbreviation	Meaning
VAS	Value Added Services
PED	Payment Entry Device
PDC	Payment Device Controller
NFC	Near Field Communication
VRK	Verifone Remote Key
KBPK	Key Block Protection Key

---