SwanPay - Embedded Payments (1214 onwards)

Created by Migration Bot, Modified on Fri, 23 Oct at 2:30 PM by Migration Bot

Originally written by John Hardwick, last updated Mar 26, 2026, on the Swan Retail knowledge base (FRS).

Click to view / download a PDF of this document

Overview

SwanFRS is capable of connecting to Clear Course payment devices (PEDs) which means where configured the act of taking a payment via a payment device is a fully integrated process without the need for the operator to key a payment value into the payment device.

Payments are encrypted and secure, with no sensitive data (such as card or cvv numbers, being recorded within SwanFRS.

This service is only available for Clear Course supplied PEDs.

When operating with integrated payments, SwanFRS also offers a ‘quick pay’ process which is a cut down version of the ‘pay and take’ process designed to speed up the process of taking anonymous ‘immediate’ sales within SwanFRS thus reducing the requirement for a Point Of Sale Till type integration.

As part of the accreditation process, Clear Course will recommend a payment device, typically they will be similar to the image below.

Configuration

To operate SwanPay a subscription is required.

If you wish to use the SwanPay, please raise a ticket with Swan Support or discuss with your implementation consultant.

It is possible to operate the quick sale process without integrated PEDs however a licence is required to release this feature.

Application Parameters

Menu Location: System Admin > Administration > Set Up Application Parameters

Set Up Application Parameters (1214 onwards)

SwanPay is controlled via the following application parameter.

Roles	Details
USE_SWANPAY_TERMINAL	This field is not user amendable. Where ticked, SwanFRS has been integrated with SwanPay. Swan will turn this on as part of installing the SwanPay feature.

Roles

Details

USE_SWANPAY_TERMINAL

This field is not user amendable.

Where ticked, SwanFRS has been integrated with SwanPay.

Swan will turn this on as part of installing the SwanPay feature.

Payment Terminals

Menu Location: System Admin > Sales > Set Up Payment Terminals

Set Up Payment Terminals (1209 onwards)

This routine holds the list of available SwanPay PEDs available within the system. At this stage we are not defining where these devices will be used, we are simply identifying the device is available for use within SwanFRS.

To set up an integrated SwanPay terminal, select the SwanPay radio button.

Field	Details
Terminal Type	This defaults to SwanPay when operating in this mode.
Payment Terminal	Specify the machine TID. The TID number is printed on the identification label on the PED or can be obtained by pressing F2 on the device. The label will be similar to that shown below
Last Counter	This is system maintained
Active	Whilst it is possible to set up multiple Clear Course PEDs, licensing restricts the number of ‘active’ devices.

This routine is licence controlled. It is possible to set as many PED devices as necessary. The licence control is on concurrent active PEDs therefore you can only make X number active at anyone time (where X is the number of SwanPay licenses you have).

Workstations

Menu Location: System Admin > Utilities > Set Up Workstations

Set Up Workstations (1209 onwards)

Once SwanFRS has been notified of the Clear Course PEDs these need linking to the location they are to be used in.

Field	Details
IP address	Create a record for each of the SwanPay PED devices in the location they are to be used. When using Fixed or Partial IP address verification, the IP specified must be within the IP range defined within that location.
EPOS ID	This field should be used to name the PED. (Short code) This field is used when selecting the payment device when processing a payment transaction. It is recommended that this code be kept short and to correspond to a code used on (label) on the PED to identify it. Leaving this field blank omits it from the list of ‘payment’ devices offered when taking payment within SwanFRS. This field is displayed when taking payments within SwanFRS and should be match the ‘name’ on the PED for example if you have 3 PEDs operating in a single store consider setting up PED1, PED2 and PED3 and labelling each device accordingly. It is also important to ensure there is a ‘non-integrated-payment’ record set against any location where financial transactions are processed by alternative methods, For example if you take cash in the location saving the results in a drawer, set up the EPOS ID as ‘Drawer’. This needs to be easily recognised by the staff as a place to deposit payments taken by non-integrated methods.
Description	This field may be used to hold a fuller description of the device.
Active	Tick to inform SwanFRS the PED is available for use within the location. It is possible to have the PED device listed in multiple locations however only one location can have the device active at any one time. This allows for a device to move between locations to cater for surges in activity (subject to the device being visible to the locations network). If this scenario is a possibility discuss whether the PED should be using a SIM card to communicate or should use the local Wi-Fi network (which may mean device setting changes as it moves between locations).
Default	Not Applicable when setting up SwanPay PEDs
Till Data Path	Not Applicable when setting up SwanPay PEDs
Customer Display Device	Not Applicable when setting up SwanPay PEDs
Is POS ?	Not Applicable when setting up SwanPay PEDs
Terminal Type	Set to SwanPay
Payment Terminal	Pick the Payment Terminal from the list provided.

It is not possible to set Duplicate Active Payment Terminal references across trading locations. i.e. a PED can only be in one location at a time, however it is possible to change to another location by removing it from the original and reselecting in the new.

If moving a PED from one location to another, mark the original location as inactive before attempting to make it active in its new location.

Locations

Menu Location: System Admin > Sales > Set Up Locations

Set Up Locations (1214 onwards)

As part of the commissioning process, along with the Merchant ID, a Site ID will be issued which will be needed for licencing.

In addition for each trading location (where SwanPay will be issuing payment requests) a local Site ID may be required, where provided this is set within Set Up Locations.

When trading with multiple companies (franchises) or if there is a variant traders ID per site. a separate series of controls and indexes will be required per trading entity.

Setting the SwanPay Config tells SwanFRS which ‘variant’ of the SwanPay portal to communicate with this ensuring that activity is linked to the appropriate branch or when dealing with different companies, payments are issues to the correct bank account.

Tender Groups

Menu Location: System Admin > Sales > Set Up Tender Groups

Set Up Tender Groups (1211)

When processing payments if the transaction is to be processed via a Clear Course PED a tender group needs defining with the Terminal Type set to SwanPay.

More than one tender group can be defined

Whilst it is possible to set a finance tender group linked to a SwanPay device this is not recommended and should not be set. Future versions of SwanFRS will prohibit this.

It is also possible to set the ‘cash’ tender group linked to a SwanPay device, this is not recommended and will stop the ability to take cash / offer change etc if set.

For most retailers moving to SwanPay is a new means of payment and therefore it is highly recommended that a new tender group is created to differentiate between non-integrated payments / refunds and integrated ones. Consider setting up a tender group named ‘SwanPay’ or ‘Integrated Payments’.

Tender Types

Menu Location: System Admin > Sales > Set Up Tender Types

Set Up Tender Types (1211)

When specifying the actual form of payment, any tender linked to the SwanPay tender group will show the legend ‘SwanPay’ in the Terminal Type column.

When creating new tender type payments consider whether SwanFRS is to automatically break out the levee charged for electronic payments and post this value to a ‘subsidy’ account code.

It is recommended that new tender types are created for payments received via the SwanPay system. SwanPay payments cannot be edited or cancelled although they do need to be ‘cash reconciled’.

Any card payment made before moving to SwanPay or manually processed outside of the integrated payment system may require editing or manually keying into the card reader / recorded in SwanFRS therefore a separate Tender Group / Tender Type is needed.

SwanFRS does not require refunds to be processed against the original payment card (although this is a future development). It is important to consider how a refund may be processed once this verified refund functionality is available and set the appropriate payment tenders whilst configuring this new element of SwanFRS.

It is recommended that a separate tender type is generated if you wish to allow ‘customer not present’ and / or ‘manually keyed card number’ transactions. Creating a separate tender enables easier identification or payments and control of use.

When used the operator will be asked by the PED to key in the card number along with other information such as expiry date, CVV and / or numerical elements of the registered card holders postcode.

Tender Type Bank Codes

Menu Location: System Admin > Sales > Set Up Tender Types Bank Codes

Set Up Tender Type Bank Codes (1205 to 1213)

The final set is to ensure the tender type has been made active in the trading location via Set Up Tender Type Bank Codes

SwanPay Configuration

Menu Location: System Admin > Sales > Set Up SwanPay Configuration

Set Up SwanPay Configuration (1214 onwards)

This routine requires the ADMIN_HEADER privilege to access however care should be taken when changing details as this can stop the embedded payments process from working.

The screen is set in to several sections, mainly for reference purposes with hyperlinks to the maintenance routines controlling the data sets.

The first section holds the SwanPay trading licences and controls, one record per location (when using Merchant Site IDs) or one record per trading entity (company / Franchise) is required.

Swan Techinical team will generally build this data as part of the commissioning of SwanPay.

Operation

Integrated Payments

There are several places within SwanFRS where a customer payment (or refund) are entered, when a tender is marked as a SwanPay payment method the system will require the transaction is processed via the PED.

Back Office Operation

The ‘standard’ accept payment window display as shown below

This page allows for multiple tenders to be processed in a single action associating the payment to a customer for on account payments or to a sales order when clicked from the side panel when viewing a sales order (as per the example shown above).

Only Tender Types NOT linked to a SwanPay payment device will be offered for selection.

This page is now driven by the operators standard trading location and the default Till Number associated to the location or operators terminal.

If the Till number is linked to a SwanPay terminal the screen will present as follows -

The PED payment page is restricted to processing a single payment at a time.

The Tender Type pick list will offer only those forms of payments defined within the Set Up Tender Type routine for the selected payment branch where the tender type has been linked to a tender group which is intern linked to a SwanPay PED.

Clicking the ACCEPT button, having specified the tender type, amount and optionally reference instructs SwanFRS to send a payment request to the linked PED device.

The screen will pause at this step waiting for the payment to be processed on the PED.

control will only return to SwanFRS once the payment has been completed on the PED (whether the payment is accepted or rejected) or if the system cannot connect to the device.

Accepted payments are recorded against the sales order / customers account as per any other direct customer payment transaction within SwanFRS.

Once the payment has completed on the PED, SwanFRS displays the following message.

Typical PED Display

Whilst waiting for a payment to be sent through the screen will display the READY message.

When waiting for the customer to process a payment then screen will show the word SALE and the value to be paid. (for refunds this will show the work

Once processed the display will show the word APPROVED

Words PRINTING - Please Wait shows when the receipt is being printed before returning back to the READY message where control moves back to SwanFRS.

Cash Reconciliation

There are no changes to the process of cashing up, all payments processed via the SwanPay PED will require processing in the routine.

It is important to note that it is not possible to EDIT a payment generated via the SwanPay process whether the payment has been reconciled or not.

Refunds

The process of refunding a customer replicates that of a payment.

The Till Number dictates the refund types offered. If the Till is linked to a SwanPay device only tenders linked to that form of payment will be offered.

There is no enforced like-for-like refund controls within SwanFRS a refund can be offered in any available format.

Tablet Operation

When processing payments on a tablet, the Payments tab offers the option to change the Till Number (and subject to permission Payment Branch) .

Dependant upon the Till selected the Tender Types offered will include only tenders linked to the SwanPay payment device or non-SwanPay payment devices.

Idempotency

The dictionary definition of idempotency is.. the property of certain operations in mathematics and computer science whereby they can be applied multiple times without changing the result beyond the initial application.

From a SwanFRS perspective, this occurs when the same transaction is sent to the same PED which would result in a duplicate request for payment. This situation rarely occurs, however it is possible t achieve if the operator uses the back button on the browser during the wait screen for example (there other circumstances).

To minimise this minor risk, SwanFRS has a 60 second check period whereby if the exact same request is sent to the same payment device within this time frame then the second (duplicate) request will be blocked.

If a customer wishes to pay the exact same amount using the same card for the same order within 60 seconds of the first payment occurring, the solution is simply to wait for a minute before submitting the same request.

Testing

Once configured and in partnership with your SwanPay consultants it is important to ensure the payment engine is working as desired.

Ensure SwanPay payments are taken for -

Initial deposit values
Secondary payments
On account Payments
Refunds against sales orders
Customer overpayment Refunds (allowances issued as credits)

if using the tablet, ensure initial and secondary payments process correctly, (it is not possible to process refunds via the tablet operation).

It is not possible to send multiple payment requests to the same PED at the same time. For example if a tablet sends a payment request to PED1, until the device completes the transaction (or times out), any request to send payments to the same device will produce ‘The PED device is not responding - cancelling the request - please check the device and resubmit the payment’ message and the transaction request will be immedidately cancelled.

When processing a payment SwanFRS will ‘freeze’ processing until the integrated payment device completes the transaction, however if this transaction takes more than 3 minutes SwanFRS will cancel the transaction and return control back to the operator,

From a PED perspective partial processed requests are cancelled after 6 mins.

Warning Messages

When communicating with the SwanPay device FRS may produce an on screen warning. The list below identifies these warnings and the steps to resolve them.

The PED device is not responding - cancelling the request - please check the device and resubmit the payment - This is caused when the PED devices has not responded to requests for 3 minutes, Check the status of the device.
The PED device appears to be off line / not connected - This message is caused when FRS cannot connect to the device, it may be the PED is powered off or the connection to it has been lost
A duplicate transaction detected, Please check and try again. - This message appears when FRS senses a payment request has been issued for the same sales and value within 60 seconds. If the repeat payment is valid wait a minute and then resubmit the request.

Reporting

As part of the SwanPay integration it is possible to plug in an audit report listing payments made during the analytical period.

The SwanPay audit may need adding to your Report Links.

Set Up Report links (1205 onwards)

SwanPay Audit

Exception Reporting / Issue Resolution

In the unlikely event that a payment completed its processing via the PED, the payment reached your back account (meaning you, the retailer has taken the payment) but the monies haven’t been reported back into SwanFRS remedial action will be required to inform SwanFRS of the payment.

The recommended approach for this as documented below.

Prior to processing it is recommended that a payment tender type is set up for manual PED adjustments and protected such that only empowered operators can use it (This is best done by restricting the tender type to an admin location).

It is recommended that a SwanPay adjustment account be set up to facilitate manual insertion of part processed SwanPay transactions.

Set Up Tender Groups (1211) - Set up a group for manual SwanPay adjustments

Set Up Tender Types (1211) - Set up a tender type for manual payment adjustments

Set Up Tender Type Bank Codes (1205 to 1213) - Set up the manual adjustment to post to an account code within the ledger allowing adjustments to be monitored and restrict use to a designated adjustment location (if not set it is recommended that an admin location be used).

To check for anomalies, run the report either in ‘Exceptions Only' mode or check the total section of the report for the red ‘one or more payments did not complete’ message.

If this occurs run the report in detail mode to highlight the payments processed where the payment value did not reach SwanFRS.

In the example below, there are three payments processed and completed by the PED which failed to update SwanFRS, these are shown in a red font.

Alongside each transaction is the recommended ‘payment reference’ which when used ties the manually generated adjustment payment to the part processed SwanPay transaction. The payment reference is zz then a reference code followed by a .0. Any combination of characters can be used to suffix this code if desired however if this code is not used the audit will not be able to link the manual adjustment to the original payment. The ‘zz’ is not case sensitive and any number of payments may be made against this code.

Remember all manually entered payments will require processing via the Cash Reconciliation process and therefore an audit trail of who processed what when can be obtained.

When registering the payment use this reference in the highlighted field.

Adjustment payments should NOT be processed via the integrated payment device as this would double up the customers payment and require the client to present their payment card.

Once processed with the appropriate reference number, re-running the audit report will include any manually entered payments linked to the SwanPay transaction with a yellow background.

It is possible to append other codes, text to the selected payment reference should there be adjustments or split payments.

SwanFRS will not force full payment or like for like customer payments however it will list all processing using the reference for the specific SwanPay transaction.