Configure, Run, and Test PayServer

Follow these instructions to configure, run, and test your PayServer integration.
Downloading PayServer
Use these links to download the PayServer bundle for Windows:
Configuring PayServer
Before running PayServer, you must supply a configuration file that contains instructions about how the server is to run and which devices are connected to it. The
config.yaml
file is located in the
server
folder (the same folder as the server Jar and the run script).
The configuration file is defined in YAML format and must have the structure shown in the example below. 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 . These elements are returned in some responses from the server so you have the option to show them in your UI.
The PayServer Windows bundle includes 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.
You can configure these optional settings:
  • 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 PayClient Integration.
  • Set the optional
    devices[].keep_alive
    to true, if you want 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 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 PayServer
PayServer runs as a background Windows Service. The PayServer bundle includes an Install PayServer Service shortcut icon on the top level. Double-click the
Install PayServer Service
icon to install and run PayServer as a Windows Service.
PayServer will then automatically start and shut down with the Windows PC. This feature eliminates the need for your merchants to run PayServer manually. The service is also monitored and automatically restarted when there is an issue. You can manually restart PayServer by clicking the
Restart PayServer Service
shortcut.
Be aware that you must restart the service every time you change the configuration via the
server/config.yaml
file. If you need to maintain more control over PayServer, there are more advanced ways to run PayServer.
Stopping PayServer and Uninstalling the Service
To stop 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 PayClient 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.
Obtaining Open Source Software
The software included in this product may contain binary code governed by the GPL or other open source licenses that give you the right to receive source code for that binary (“Licenses”). You may obtain the source code you are entitled to under the Licenses by sending a money order or check for US$50 to:
Payworks GmbH
Dingolfingerstr. 15
81673 Munich
Germany
Your request should include your contact information as well as the name and version number of the binary for which you are requesting the source code.
This offer is valid for (i) a period of three years after our last shipment of this product or (ii) for code licensed under AGPLv3, GPLv3, or LGPLv3, for as long as Payworks offers customer support for the product.
For more information about the use of open source software, contact Customer Support.