FreedomPay Integration – Device setup guide

Companion to the front-desk guide. That one is for the person taking payments; this one is for the person who takes a terminal out of its box, registers it, keeps it updated, and pulls logs when something goes wrong.

This page covers Enterprise Portal administration. It assumes access to your FreedomPay Enterprise Portal and is aimed at StayFlexi onboarding staff and the merchant’s own administrator.

Which integration shape we are

FreedomPay’s guidelines describe two command-template shapes. StayFlexi is Exhibit A.

Shape	Description
Exhibit A — external POS ✅	The POS is not an Android app on the Castles device; it calls CX from elsewhere.
Exhibit B — on-device POS	The integrator’s app runs on the Castles device alongside CX.

StayFlexi is a cloud PMS. Our servers call FreedomPay Cloud Middleware (CMW), and CMW reaches the CX application on the terminal. Nothing of StayFlexi is installed on the device. This is why our command template uses the External POS or Standalone command set and never Install New Application (3rd Party).

The practical consequence for a merchant: the terminal needs internet, not a link to the front-desk PC, and the fleet is managed entirely from the Enterprise Portal.

Permissions you need

Task	Role	Permission
Build a command template	Device Management – Premium	Manage Command Templates
Schedule a command	Device Management – Premium	RUS Administrator  or  RUS Commands (Write)

If the Enterprise Portal does not show Command Templates or Scheduled Command, it is a permissions problem, not a missing feature. Ask your FreedomPay Success Manager.

What changes between UAT and Production

Everything below lives in cx.config.json, which is uploaded to the Enterprise Portal and pushed to the device. The two environments are separate Enterprise Portals with separate credentials — a value from one never works in the other.

Cloud Middleware server addresses

This is the setting that makes CX talk to the right environment, and the most common cause of a terminal that registers but never transacts.

How the three slots behave. CMW connects to all of them and prefers slot 1. If slot 1 is unreachable it falls back to slot 2, then slot 3. Configure them for your operating region: for a US merchant in Production, slots 1 and 2 are US and slot 3 is a European backup.

Server blocks to copy

UAT

"Servers": [
  { "Name": "cluster_00", "Address": "amqps://msg01-use2.cmw.uat.freedompay.com:5671" },
  { "Name": "cluster_01", "Address": "amqps://msg01-usw3.cmw.uat.freedompay.com:5671" }
]

Production, US merchant

"Servers": [
  { "Name": "cluster_00", "Address": "amqps://msg01-use2.cmw.freedompay.com:5671" },
  { "Name": "cluster_01", "Address": "amqps://msg01-usw3.cmw.freedompay.com:5671" },
  { "Name": "cluster_02", "Address": "amqps://msg01-euw1.cmw.freedompay.com:5671" }
]

The rest of the environment-specific settings

"MerchantSettings": {
  "EsKey":      "<environment-specific>",
  "StoreId":    "<environment-specific>",
  "TerminalId": "<environment-specific>"
},
"OperationMode": {
  "CloudMiddleware": {
    "Enabled": true,
    "CloudMiddlewareSettings": {
      "WorkstationID": "",
      "UseMachineName": true,
      "DisplayHotelRoomRate": true,
      "Servers": [ ... ]
    }
  }
}

DisplayHotelRoomRate is a lodging setting and should be true for hotels. StayFlexi sends the pre-tax room rate and the room tax as separate values so they reconcile to the charge amount, and this is what surfaces them on the terminal.

Every other OperationMode block — Standalone, TcpIpClient, UsbClient, IntentClient, PayAtTable — stays false. We are cloud middleware only.

Admin credentials

AdminAccessCode and AdminPassword secure the on-device Administrator menu. Change both from their documented defaults before go-live — the defaults are published in FreedomPay’s own documentation, so a device left on them is effectively unsecured. If a code is lost, push a fresh cx.config.json with a new value to force a reset.

Never put an EsKey, access code or password in a ticket, an email or a chat message.

The version tag — the setting that silently does nothing

When you edit cx.config.json or arus.config.json, increment the Version tag above the version currently on the device. A config pushed with the same or a lower version is accepted by the portal and ignored by the device. The command reports success and nothing changes, which is a hard failure to diagnose. If a config change appears not to have taken, check the version tag first.

Command template — initial registration only

A command template is the unboxing path: the merchant scans a QR code and the device pulls down everything it needs in one pass. It is strictly for first registration. Once a terminal has registered, every later change goes through a Scheduled Command instead.

Only one registration method is used per device — either a command template with a QR code, or manual DMP key entry through ARUS. Not both.

Building it

Device Management → Command Templates

1. Click Create Template.
2. Enter a Name and Description. Name it for the environment — a template pointing at UAT that gets used on a production device is the most expensive mistake available here.
3. Under Select Commands, add the commands below.

Commands run in the order you select them, so the order below is the procedure, not a list.

Scheduled commands — everything after registration

Scheduled Commands become available once the Remote Update Service has registered; the middleware then appears under its machine name in Middleware Search.

The pattern is the same for all of them: select the middleware instance → Scheduled Command → choose the command. After scheduling, use the status button in Middleware Search to confirm it actually ran. Scheduling is not completion — a device that is off or off-network leaves the command pending indefinitely.

Get Middleware Log Files

The first thing to do when a terminal misbehaves, and the first thing FreedomPay support will ask for.

1. Middleware Search → select the middleware instance for the terminal.
2. Select Scheduled Command.
3. Choose Get Middleware Log Files.
4. Select the date range covering the incident.
5. Schedule it, then watch the status button until it reports complete.
6. Download the returned files from the Enterprise Portal and extract them locally.

Applies to both CX and ARUS, so pull both when the problem is not obviously one or the other: a terminal that never received a command is an ARUS story; a transaction that reached the terminal and failed is a CX story.

When you send logs to FreedomPay, include the Request ID, the booking ID, the timestamp with time zone, and what you expected to happen. StayFlexi support can supply the Request ID from the payment record.

Download PAL Package

PAL packages carry the regional and processor-specific EMV configuration. A terminal without the right one may register, connect, and still decline every chip transaction.

First, upload and publish the package — a package that exists but was never published cannot be selected:

1. Device Management → PAL Packages
2. Upload the package.
3. Options → Publish.

Then push it:

1. Middleware Search → select the middleware instance.
2. Select Scheduled Command.
3. Choose Download PAL Package.
4. Select the published package.
5. Schedule, then confirm via the status button.

On the device, CX applies the package and the reader begins completing chip transactions normally. Verify with a live chip transaction rather than by command status alone — the status reports that the file arrived, not that the EMV configuration is correct for your processor.

Packages are reusable across merchants on the same region and processor, so the working set is small. Moving to production is where this usually bites: the production processor is frequently not the one used in UAT, and the UAT package will not do.

Update Middleware Config

For changing cx.config.json or arus.config.json after registration — new receipt headers, a changed admin password, different server slots.

1. Edit the file locally. Increment the Version tag.
2. Device Management → Middleware Config Manager → Upload. Select the top-level hierarchy, set a description, upload, then Options → Publish.
3. Middleware Search → select the instance → Scheduled Command → Update Middleware Config → select the file → schedule.

One file, one instance, one command. Changing both arus.config.json and cx.config.json means two separate scheduled commands.

Install New Application

For updating CX itself after registration. On the configuration screen, click Next — config updates are not supported as part of an application update and must be scheduled separately afterwards.

Go-live checklist

• Production Store ID and Terminal ID received from FreedomPay boarding
• Production cx.config.json built — production EsKey, production CMW server addresses, CloudMiddleware.Enabled: true, all other operation modes false
• DisplayHotelRoomRate set to true
• AdminAccessCode and AdminPassword changed from the documented defaults
• Version tag incremented above whatever is on the device
• Server slots ordered for the operating region, slot 3 a different-region backup
• JSON validated — no trailing commas
• Production command template built in the production Enterprise Portal
• Production PAL package uploaded and published for the production processor
• Firmware current
• Network open per the front-desk guide: outbound 443, and UDP 123 for time sync
• Device date, time and time zone correct, automatic time on
• Get Middleware Log Files exercised end to end — scheduled, completed, downloaded
• Download PAL Package exercised end to end, verified with a live chip transaction
• One live transaction of each type StayFlexi uses: sale, authorization, capture, void, refund, saved-card charge
• StayFlexi payment settings updated with the production Store ID and Terminal ID