Configure, Run, and Test PayServer

Use the following instructions to configure, run, and test PayServer.
Downloading the PayServer
Download the PayServer bundle for Windows:
Opening Source Software
Open source software is used in PayServer. For more details, see the
License
 file in the bundle (inside the META-INF directory of the payserver jar). You can download the source code of the (L)GPL and CDDL licensed software. For more information about the use of open source software or access to the source code of the open source software, contact Customer Support.
Configuring the PayServer
Before running the PayServer, you must supply a configuration file, which tells the server how it should run and what devices it has connected. The file is named
config.yaml
 and it has to be placed in the
server
 folder (the same folder as the server Jar and the run script).
The configuration file is defined in YAML format and should have the following structure. The file is a full sample configuration file with all currently available options annotated with comments.
server:
  -
    protocol: P3                    # P3 protocol
    transport: WEBSOCKET            # over WebSocket connection
    port: 8080                      # port number
  -
    protocol: P3                    # P3 protocol
    transport: FRAMED_TCP           # over framed TCP connection
    port: 8081                      # port number

devices:
  # sample configuration for a mock device which can be used for testing
  -
    name: Mock Device               # human readable device name
    identifier: mockDevice          # unique identifier (will be generated randomly if omitted)
    type: MOCK                      # device type
    comlink: MOCK                   # connection type

 
# sample configuration for a Miura reader connected via USB
  -
    name: USB Miura                 # human readable device name
    identifier: usbMiura            # unique identifier (will be generated randomly if omitted)
    type: MIURA                     # device type
    comlink: USB                    # connection type
    port: COM3                      # virtual port name
    keep_alive: true                # the device will be kept connected between transactions (false by default)
    idle_text: ["custom text", "with multiple", "lines", "      centered"]        # custom text that appears when the reader is in idle state


  

information:                        # optional extra information
  location: 3rd Room                # human readable name of the server location

settings:
  locale: en                     # locale to be used independent from the system one
  transactions:
#    enable_signature_actions: true  # specifies if transaction process will send out signature actions
The server can handle serving multiple protocols at the same time but for most use cases only one server configuration is needed. If you intend to use the .NET Pay Client, use
P3
 as the server protocol and
WEBSOCKET
 as the transport option.
The
location
 and
name
 for a device are not required . They are returned in some responses from the server so that you can display them in your UI if you would like to.
In the PayServer Windows bundle we include a sample configuration file named
config-example.yaml
 located in the
server
 subfolder. This file is correctly configured to be used with the .NET Pay Client but make sure to review the device list before applying it.
Optional settings include:
  • Set the optional
    settings.transactions.enable_signature_actions
     to true, if you want to capture the shopper's signature digitally and not on the physical receipt. After enabling this option, the signature action messages will be sent out during transaction processing and you need to implement the accompanying signature capture logic in your POS. For more information about signature actions, see P3 Usage and Message Flows and Pay Client Integration.
  • Set the optional
    devices[].keep_alive
     to true, if you want the PayServer to stay connected to that particular device after you execute a transaction on it. This will increase the transaction speed but also prevent the device from entering standby mode. Beware that the device will be connected until you disconnect from the PayServer or until you use another device for a transaction.
  • Set the optional
    devices[].idle_text
     to any custom idle text that should be shown while the device is in keep-alive state (i.e., no transaction is done, but the connection to the device is kept alive). Provide max 4 lines with 20 characters each and prefix the text with spaces to center it.
Running and Restarting the PayServer
The PayServer runs as a Windows Service in the background. In the PayServer bundle you'll find a
Install PayServer Service
 shortcut on the top level. Double-click it and it will install and run the PayServer as a Windows Service.
The PayServer will then automatically start up and shutdown with the PC, so that your merchants do not have worry about running the PayServer. The service is also monitored and automatically restarted in case there was an issue with the PayServer. In case there appears to be a problem with the PayServer and you want to restart it, you can do so using the
Restart PayServer Service
 shortcut.
Keep in mind that you need to restart the service every time you change the configuration via the
server/config.yaml
 file. If you need to have more control over the PayServer, there are more advanced ways to run the PayServer.
Stopping the PayServer and Uninstalling the Service
To stop the PayServer and uninstall the service, use the
Remove PayServer Service
 shortcut.
Performing a Test Transaction
To verify that everything is working you can perform a test transaction:
  1. Download and run the Pay Client Tester App.
  2. Fill in the host. Copy and paste your
    merchantIdentifier
     and
    merchantSecretKey
    .
  3. Click the
    Connect
     and
    Start Transaction
     buttons. When you start the transaction, the Tester client executes it on the first device from the list of devices. To make sure your device is selected, configure the server for only one device at first.