Default configurations

A common setup for all your customers' devices allows you to personalize their devices into one group, having default behaviors based on their needs. Multiple groups of devices can therefore be deployed and maintained.

Automatic deployment

If needed you can make a change to your live group of POS devices. This is done via the Central backoffice. The new parameters are silently communicated across systems, no interaction needed in PayXpress.

The controls:

The following personalizations can be added or hidden in the app:

1 Enter amount screen
2 Support page configuration
3 Multi-currency
4 Franc Pacifique (XPF) display amounts
5 Main menu and PIN/no PIN customization
6 Offline mode
7 Company logo for screen saver
8 Logo on ticket
9 Card brand display
10 Tips
11 Demat configuration
12 Sessions
13 Transactions history
14 Daily summary
15 File collection history
16 Pay by link

Enter amount screen

Controls the main screen of the app. Enable this screen to so that your employees can initiate in-store transactions.

For this to occur the enter_amount_enabled parameter must exist and should be set to true.

On the contrary, if the device is to be controlled by cash register via the Concert machine protocol, this would be set to false, the screen saver page being shown in between payments.

Support page configuration

You can control the text size and the text itself, controlling contact numbers etc.

This is done by providing your own Java parameters in the value for the support_page_content parameter.

Multi-currency

Payxpress can inherently accept cards with balances in other currencies, supporting business areas like tourism. The payout you receive is in your local currency (i.e. EUR).

However, the addition of the multicurrency_enabled parameter enables the merchant to select another currency in the Settings menu, to display the payment screen in that currency, and to be paid out in a settlement account in that currency.

If you have additional bank accounts you can be paid in other currencies such as GBP and USD.

Please note that processing multiple currencies is not the same thing as Currency Conversion (DCC), which requires an additional Merchant account and contractual agreements with the external provider.

Franc Pacifique (XPF) display amounts

In DOM/TOM territories we can display the sales amount in XPF for the local customers.

PayXpert must set the conversion_rate of this feature.

Available with Ezyness bank in Gateway mode.

Availble on the Castles S1F2.

You must enable the main menu and state which items you want to show. The items can be PIN-protected or open.

Build a main menu

For your case, you can show/hide the areas relevant to your merchant. For the burger_menu_item parameter, give it the following values, as desired:

Transaction history (= Transactions' journal).
See Transactions history for feature.
Settings Parmeters for:
- originators- to set for an alternative shop
- security- setting PINs. See Admin PIN for sensitive areas and actions for feature
- concert - to pair with device
- set default transaction type
- tips - to allow the merchant to set his own Tips preferences. For feature seeTips
- debug
- logs
About page
Support page
Exit - allows merchant to quit the app

On the Sunmi P2 Smartpad, the main menu is null. The app is controlled by the cash register and only the cardholder interacts with the device (presenting his card on the payment screen etc).

Show no Main menu at all

If you want to hide the Main menu completely, set burger_menu_item to null.

No main menu will be available in PayXpress, only the payment screen:

Set up a hidden Main menu

It is possible to not show the Main menu per se (in order to avoid unwanted access) but to let the user activate it via a 'magical' invisible area on the screen. To do this, create a new parameter called hidden_burger_menu and set it to true.

In order to activate the hidden menu, the user must press and hold the area in the top right of the input amount / waiting screen for 5 seconds:

PIN controls

Enforcing a PIN and where to enforce it is completely customizable.

1 Admin PIN
2 Merchant code
3 Android system bars

Admin PIN

Controlling access to the desired menu items (or not) is set via:

the Admin PIN (if not set to none)
- Forces a PIN when trying to access
- The PIN is the same value for all menu items desired
- Set the menu items to restrict by creating a parameter called admin_code_restrictions and setting it to the name of the menu item (all is also possible):
  - History
  - Daily_summary
  - Parameters(settings)
  - About
  - Support
  - Exit

Available formats (one is needed):

Set the admin_code yourself: eg. 123456
You can set the actual value of the PIN if setting a (6-digit PIN) and reference it when the customer forgets it.
Set the code to depend on ddmm:
You can set the Admin PIN to have a special ddmm format so that the PIN changes daily.

The Admin PIN must be configured remotely at the POS group level.

The merchant cannot set the Admin PIN at first Init.

The merchant cannot change the Admin PIN. If the merchant forgets it, he/she must contact the relevant Support team. The value must be retrieved by viewing the POS group.

Merchant code

This PIN code is also configured remotely, initially. It must be given an initial value when it is configured to exist for either or both operations.

However, the Merchant can reset his Merchant code if forgotten or not known—this action will require the Admin PIN if an Admin PIN is configured.

If the admin code is set to none, the merchant could change the Merchant code without this level of security. The reseller/partner is responsible for the app security they build.

A Merchant code can be set for Cancellations, Refunds, or both operations. This protects these operations.

Available formats (if not set to none):

set the merchant_code yourself
You can set the actual value of the Merchant code if setting a (6-digit PIN).
set the code to depend on ddmm: You can set the Merchant code to have a special ddmm format so that the PIN changes daily.

Merchant code restrictions

The merchant_code_restrictions control allows you to specify which transactions require a pin—Cancellations and/or Refunds.

The Merchant code can also be enabled when performing a “force transaction” operation which allows the operator to send a low-risk transaction if the POS prompts for it. This can happen on rare occasion when the merchant’s bank would like the PayXpress POS to accept a transaction whose authorization was inconclusive.

Android system bars

Custom navbar prompts PIN

Limit accidental Android navigation access by selecting one of the following:

none - disables the bottom bar
custom_with_pin - operator must enter the Admin PIN to exit the payment screen or app
default - displays the full bottom bar, enabling standard Android navigation

Offline mode

Enables the merchant to perform basic transactions if their POS loses connection

Within the offline_mode control you can have the feature perform silently or prompt the merchant if he would like to continue with the offline transaction. The controlling values are:

NOT_AUTHORIZE: Offline mode will not be possible
AUTHORIZE: Offline mode will work silently
WITH_CONFIRMATION: Offline mode will work with a confirmation pop up for the merchant to continue

In this example, offline_mode = with_confirmation

You can also personalize the following limits:

maximum number of transactions to do offline by setting a value for offline_max_transactions
maximum amount that can be reached in offline transactions by setting a value for offline_max_transactions_amount

The POS and the Central Backoffice remember that the transaction was performed this way, so when displaying it in the Transactions journal or in the Transaction details page it will be denoted.

For full rules, see Offline mode.

Company logo for screen saver

It is possible to use your own logo (replacing that of PayXpress) on the loading screen ->

GIFs and images are supported.

Ensure the image is of good quality and 2Mb or below. The background must be transparent.

For now, this control requires Concert to be enabled on the device.

To activate this personalization, set screensaver_enabled to true and request support for the insertion of your file.

Optionally, set a screensaver_delay parameter to a seconds (s) number value. By default the screensaver appears after 15s.

This control is at the Company level and it is a POS group parameter.

Please contact Support so that we can perform this change in the Backoffice if desired.

Logo on ticket

Allows you to parameterize a merchant’s logo to appear on the transaction ticket.

Reserved for custom arrangements.

This and other more generic look and feel personalizations are planned for future.

Card brand display

Controls which card scheme icons to display on the payment screen.

In process of being moved from Merchant account parameters

Tips

You can enable the Tips feature for the whole group of like devices. Tips is a helpful personalization if your merchant is in Restaurants, Transportation, etc.

To activate Tips, set tips_enabled to true.

Then, the Partner can enforce remote ‘tips’ parameters by creating them on the POS Group. Otherwise, the merchant will have local control of the tips parameters on each device.

Explanation below.

If desired, set with_shortcut to true. This lets the merchant turn Tips off (in the payment flow) in peak hours of the day where conducting transactions is more important. The operator (e.g. waiter) can turn it back on when the rush is over.

Tips shortcut set to ON

To enable/disable the printing of the tip on the virtual/paper ticket, also set tips_printing_activation to true:

Tips printing is ON

Remote or local controls?

If you want to enforce tip values and format:

Set tips_values to the desired numbers (ex. 5,10,15) to enforce the tips %s, otherwise the merchant will be able to change them manually (locally) in the app.
also set tips_format to the desired format, otherwise the merchant will have the choice. If you need to set the format remotely, choose one of the following:
- AMOUNT→display the amount rounded sup only (legacy mode)
- PERCENT_ROUNDED→ display the amount rounded sup + the percent value
- PERCENT-> display the amount NOT rounded sup + the percent value

In this example controls are enforced; the merchant does not have the option to adjust settings:

In this example, there are not tips parameters set remotely so the merchant can adjust them locally:

For all the functionalities on Tips: Tips.

Demat configuration

Cardholder

Merchant

You can personalize which Dematerialization options are offered to the cardholder. After setting demat_cardholder_enabled the following can be enabled or disabled:

Virtual ticket: virtual
paper ticket: paper
QR code: qrcode
Email ticket: email

For example: virtual,email,paper

For merchant ticket dematerialization, set demat_merchant_enabled to:

paper
email
qrcode

…as desired in order to show these options.

For example: virtual,paper

Full info on Dematerialization:

Dematerialization options.

Sessions

The merchant can organize their transaction activity into business hour work shifts if he or she desires, defining the end times of the shifts.

Merchants can also end / begin a session spontaneously.

Virtual session ticket

If Sessions are enabled, the merchant can navigate the Main menu but must start a session to accept payments:

Transactions history

This essential feature allows the merchant to filter for past transactions in the date range and for the criteria they desire, printing statistics or pinpointing individual transactions in question.

In order to appear on the POS, you must create the parameter transactions_history_enabled on the POS group and set it to true.

For full info on this area of the PayXpress app see Transactions history.

Transaction breakdown per day

Daily summary

Enables the merchant to set their business day hours and check current or most recent business day block of activity.

To enable, create a daily_summary_enabled parameter on the POS Group and give it the value true.

As for sessions, a recap ticket can be shared or printed. The merchant can have both Sessions and a Daily summary.

File collection history

Enabling this PayXpress feature allows the merchant to get a TLC (File collection) overview of his group of POS terminals from any terminal. It is a shortcut for the merchant who has a more detailed File collection page in the Central Backoffice. Remitted files are listed in the terminal for the last 7 days. The backend sends the terminal info about “sent for settlement” or failed files only, not about files awaiting sending.

The file_collection_history_enabled parameter must be assigned to the POS Group and set to true.

The feature is available on the main menu.

The 7-day default history is standard.

Manual file collection

To enable the merchant to trigger their own file collection (an extra feature once File collection history is enabled), set file_collection_trigger_enabled to true.

Using the “upload” button the merchant will then be able to trigger his own transaction file remittance manually:

Manual file collection

Pay by link

It is possible to use the phyiscal POS terminal to generate & send an online payment link. It is emailed to the client with the order amount and details all ready in a payment page window of an e-commerce transaction. The POS displays and tracks the status and details of the payement.

This feature is not enabled per POS group: you must request Support for an ecommerce merchant account to be created for you and associated with your Device (via Originator; the Payment page must be activated on it).

Please specify which email to use so they can paste in the “Email from” field.

For more info see https://payxpert-docs.atlassian.net/wiki/spaces/docs/pages/1829797903.

Using the device to create an online transaction

Concert on a group of POS devices

The Concert protocol can be enabled and set up for your POS groups if the devices will be communicating with cash registers (like is done with the Sunmi P2 Smartpad). You or your merchant are responsible for the Concert integration of their cash register systems to the protocol. The device can be configured to use the AP Concert Protocole (v3.2 by default, but this is configurable) in that case.

Mandatory POS group parameters if using Concert:

1 Enable Concert
2 Concert version (if other than the default—3.2)
3 Communication method
4 Enable the Ingenico machine (if applicable)

Enable Concert

The parameter concert_enabled must be created and set to true in order to enable the Concert protocol in the PayXpress app. Otherwise Concert is disabled by default.

Concert version (if other than the default—3.2)

By default, when you enable Concert we assume that you will be using version 3.2 of the protocol, and in that case it is not necessary to specify the concert_version. However, if you are using an earlier version, or if you will be using the PayXpert SDK, it is necessary to create said parameter (concert_version) and set it to one of the following:

310 if using v3.1 of the protocol
300 if using v3.0 of the protocol
SDK if using the PayXpert Concert Protocol SDK

Communication method

If enabling Concert than you need to specify which physical means of communication the devices will use. Create a concert_communication_method parameter and set it to one of the following:

WIFI
IP_ETHERNET
BLUETOOTH
RS_232. If using this USB cable-type connection, these extra parameters are mandatory:
- concert_speed: must be set, use one of the following:
  - BAUD_1200
  - BAUD_9600
  - BAUD_19200
  - BAUD_38400
  - BAUD_57600
  - BAUD_115200
- concert_extra_timer: must be set to true or false depending on whether you want to prevent timeouts (then true) or respect the default timeouts (then false).
  More context: In the Concert RS232 protocol, each command sent between the POS and the cash register includes a timer — if the timer expires before a response is received, it's treated as a command failure (which triggers a retry mechanism). The concert_extra_timer parameter activates an additional timer on top of the standard ones, as prescribed by the Concert specification, to handle the specific timing constraints of serial (RS232) communication.
- concert_parity_check: must be set to true or false depending on if the other device uses a parity control (usually they do not, so this value can be set to false.)
- concert_retro_compat: must be set to true or false depending on whether you will be using older versions of Concert (thentrue) or not (thenfalse). Remember that Concert version is controlled by the mandatory concert_version parameter discussed above.
  
  Note that for RS_232 connections there is more specific technical configuration that you must consider; refer to USB/RS232 - Specifications.

Enable the Ingenico machine (if applicable)

If you have chosen to use one of the Ingenico terminals that we support, then an additional parameter is needed to enable Concert on the machine. This parameter will be supplied here soon.

Optional POS group parameters if using Concert:

1 Rapid payment shortcut
2 Whitelist
3 Pair the device with the new POS group always for Concert

Rapid payment shortcut

If communication with the cash register fails (lack of connection, cash register crashes…) then you may need to make a rapid payment manually on the device. The ability to do this can be activated in the POS group using the parameter concert_enabled to with_shortcut. This will activate an options button area on the screen where the option to turn Concert off (and use the POS device manually) appears.

The operator can then manually enter the sales amount.

The shortcut is exited after one payment: the POS device then looks again for the Concert connection for any subsequent transactions. This is to prevent discrepancies between the register and the POS device. However, the shortcut can be used accessed again if needed.

Whitelist

When enabling Concert it is advisable to inform PayXpress of the cash register device’s IP or Mac address(es) so that communication is allowed—and restricted—to the desired device(s). To do this, creat a concert_whitelist parameter on the POS group and set the value to the IP of the cash register device(s), e.g. 192.168.1.10;192.168.1.11;192.168.1.12.

Pair the device with the new POS group always for Concert

This is needed to override any old data on the device and to keep it in synch with the POS group configuration in our Central Backoffice. This behavior—to use the remote Concert parameters instead of any old or mistakenly set local Concert parameters—can be effected by setting always_use_pos_group_as_concert_config_source to true.

Concert protocol - the language of the devices

Besides pairing the device and defining what type of communication to use, a full Concert protocol integration is available.

Personalization of PayXpress