FreedomPay Integration

StayFlexi connects directly to FreedomPay so your front desk can take chip, contactless and swiped card payments on a countertop terminal, with the result posted straight to the guest folio. This guide covers how it works, how to set the terminal up, how to take each kind of payment, and what to do when something goes wrong.

Applies to hotels using the FreedomPay CX application on a Castles all-in-one terminal.

How a card payment works

StayFlexi talks to FreedomPay’s Cloud Middleware, which talks to your terminal. Your front-desk computer never talks to the terminal directly.

1. You start the payment in StayFlexi. Open the booking and choose Charge, Authorize or Refund.
2. StayFlexi sends the request to FreedomPay. This happens server to server, over the internet.
3. FreedomPay wakes your terminal. The CX application on the terminal receives the request and displays the amount.
4. The guest presents their card. Insert, tap, swipe, or key the card in on the terminal.
5. The card is authorized. Card data is encrypted on the terminal and sent to FreedomPay, then on to the processor, the card scheme and the issuing bank, and back the same way. Card numbers never reach StayFlexi.
6. The result comes back to StayFlexi. Approved or declined, with an approval code and a Request ID.
7. StayFlexi records it. The payment is posted to the folio with the card brand, last four digits, approval code and Request ID, and the receipt text from FreedomPay is added to the guest receipt.

Three things this means in practice

• The terminal needs its own internet connection. It does not need to be plugged into, or on the same network as, the front-desk computer.
• Closing the browser does not cancel the transaction. If you close the tab while the terminal is waiting for a card, the terminal keeps waiting and the payment can still go through. Cancel on the terminal instead.
• Wait for the terminal before clicking again. Each click starts a new transaction. Clicking twice while one is in progress will fail with a Device Busy error.

Before you start

Three things have to be in place before the first payment. Your StayFlexi onboarding contact arranges all of them with you.

Store IDs and Terminal IDs identify your property to FreedomPay. Treat them like account numbers: they belong in your StayFlexi settings, not in emails, chat messages or shared documents.

Setting up the terminal

Network

The terminal can use Wi-Fi or Ethernet. Wi-Fi is set during the guided first-run setup. For Ethernet, or to set a static IP, your installer will configure it through the device’s system settings — these steps need an administrator password that FreedomPay supplies directly to your installer.

Date and time

The terminal must have the correct time zone and automatic time enabled. A terminal with the wrong clock will fail to connect to FreedomPay and every transaction will decline. If transactions start failing after a power cut, check the clock first.

Where to put it

Within the guest’s reach at the desk, with a clear view of the screen for entering a PIN. Give it a stable power source — a terminal that loses power mid-transaction leaves an authorization that has to be voided by hand.

Taking payments

Holds and how long they last

An authorization is a hold, not a payment. How long it stays on the guest’s statement is decided by their bank, not by StayFlexi or FreedomPay — usually a few days, sometimes longer. If you void a hold, the release is immediate on your side, but the guest may still see it on their statement for a short while. That is normal and worth explaining at the desk.

Saved cards

When a guest pays with a card, StayFlexi can keep a secure token for it so you can charge it again later without the card. The token is meaningless outside your FreedomPay account — it is not a card number, and it cannot be used anywhere else. Charging a saved card does not involve the terminal and produces no terminal receipt.

Partial approvals

Some cards, particularly prepaid ones, approve less than you asked for. StayFlexi records the amount that was actually approved and leaves the remainder on the folio, so you can take the balance another way. Always check the amount on the receipt against the folio balance before letting the guest go.

Receipts

FreedomPay returns the card portion of the receipt — card brand, masked number, entry method, approval code and the EMV data that card scheme rules require. StayFlexi supplies everything else: your property name, the folio detail, taxes and totals.

Both the guest copy and the merchant copy are available from the payment record on the booking. Keep the merchant copy according to your card scheme’s retention rules; your acquirer can tell you what those are for your region.

Charges to a saved card produce no terminal receipt, because no card was presented and no terminal was involved. The payment record in StayFlexi is the record of the transaction.

Network requirements

Give this section to whoever manages your network. The terminal makes outbound connections only, on port 443. No inbound rules and no port forwarding are needed.

Time synchronisation is not optional. If UDP 123 is blocked, the terminal’s clock drifts and payments begin to fail with connection errors that look like a gateway outage.

Troubleshooting

When a payment fails, the terminal and StayFlexi both show a code and a message from FreedomPay. The code tells you who can fix it.

Before you call anyone

• Is the terminal showing its normal idle screen?
• Is it connected to the network? Wi-Fi symbol, or a live Ethernet cable?
• Is the date and time on the terminal correct?
• Does the same payment fail twice in a row, or was it a one-off?
• Does a different card behave the same way?

A terminal restart clears a surprising number of problems and costs thirty seconds.

Getting help

Start with StayFlexi. We can see the payment record, the exact request we sent and the exact response FreedomPay returned, which is usually enough to tell whether the problem is the card, the network, the terminal or us. We escalate to FreedomPay ourselves when it belongs with them.

What to include

Every card transaction has a Request ID — a long reference shown on the payment record in StayFlexi. It is the single most useful thing you can give us, because it identifies the transaction exactly in FreedomPay’s systems.

• The Request ID, if the payment reached the terminal at all
• The booking ID and the amount
• The date and time, with your time zone
• The error code and message, exactly as shown
• What you were trying to do, what happened instead, and whether it happens every time
• A photo of the terminal screen, if the error appeared there

Never send full card numbers, CVV codes or card images to anyone, including us. We do not need them and cannot accept them. The last four digits are on the payment record already.