Placér dit indhold fhgfvhbher

Windows Integration – PayServer/PayClient

Configure, Run and Test the PayServer

First download the PayServer bundle for Windows:


Before running the PayServer you have to supply a configuration file, which tells the server how it should run and what devices it has connected. The file has to be 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. This 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 # sample configuration for a Verifone reader connected via USB - name: USB Verifone # human readable device name identifier: usbVerifone # unique identifier (will be generated randomly if omitted) type: VERIFONE # device type comlink: USB # connection type port: COM0 # virtual port name keep_alive: true # the device will be kept connected between transactions (false by default) # sample configuration for a Verifone reader connected on WiFi or Ethernet - name: Network Verifone # human readable device name identifier: networkVerifone # unique identifier (will be generated randomly if omitted) type: VERIFONE # device type comlink: WIFI # connection type remote: # address or DNS name of the reader port: 16107 # port number of the reader 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 server protocol and WEBSOCKET as 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.

Set 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.

Set 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 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.


The PayServer is meant to run as a Windows Service in the background. In the PayServer bundle you’ll find a Install PayServer Service shortcut on the top level: Just 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.yamlfile.

To stop the PayServer and uninstall the service use the Remove PayServer Service shortcut.


The PayClient is an easy to use library to process transactions with the PayServer. It provides a high-level implementation of the PayProtocol (P3) for quick integration.


The PayClient is currently available for the .NET Platform and can be downloaded right below.

The PayClient bundle contains all assemblies and dependencies that you need to set up your project for the PayClient. Once you added them to your project, you will have access to the PayClient classes and can start integrating with the PayServer.

The PayClient Tester App contains a small pre-build application that allows you to quickly test the connectivity to the PayServer. Just provide the remote address of the PayServer as well as your merchant credentials and you are good to go.


The PayClient for .NET comes as prepackaged assemblies that just need to be added to your project. In addition to that we have a couple of dependencies that you can also need to add manually (or use Nuget to pull them in automatically).

The PayClient itself is targeting .NET Framework 4 (and above) and should work on any Windows version that has support for this version of the .NET Framework.

PayClient Assemblies

  • Payworks.PayClient.Bridge.dll (Protocol and Models)
  • Payworks.PayClient.Core.dll (Client and Communication)

External Dependencies

  • NLog (, NLog.dll)
  • Json.NET (, Newtonsoft.Json.dll)
  • WebSocketSharp (, websocket-sharp.dll)

When you are adding the dependencies manually, you should end up with a reference tree that looks similar to this one:


Login and Device Selection

Initialize a new PosClient

First step is to initialize a PosClient instance with your credentials and the address of your PayServer instance you have running. With this instance you have access to all functionality of the PayServer.


Connect to the PayServer

Once this is done, you will need to connect to the PayServer. This will establish a connection and initialize the PayServer with your credentials. After a successful connect you will receive a list of devices that are configured and available for you to use.

PosClient.ConnectAndLogin(MERCHANT_IDENTIFIER, MERCHANT_SECRET, Environment.TEST, (devices, error) => { //check for error //use devices for interaction Device = devices[0]; });

Whenever you want to close the session, simply disconnect from the server.

PosClient.Disconnect( (error) => { //check for error //this should normally always succeed });

When you want to reconnect after a disconnect, please initialize a new PosClient instance.

Manage Devices

After successful login, you will receive a list of devices that are configured on the PayServer. You are able to use the Deviceobject to start a transaction.

Each Device also contains meta information that has been configured on the server side. Either just choose the first one on the list, or inspect the properties in more detail to select the one you would like to use.

Making a Transaction

The transaction itself is started via the ITransactionModule from the PosClient .

Starting a Transaction

When you start a new transaction, you provide the Device and the TransactionParameters that specify the amount, currency and other parameters for the transaction. The Builder() will help you create a suitable set of parameters.

var transactionParameters = new TransactionParameters.Builder() .Charge(10.00m, Currency.EUR) .Subject("Box of chocolates") .CustomIdentifier("yourReferenceForTheTransaction") .Build();

With the created TransactionParameters you can then start the actual transaction. When starting a transaction, you will have to provide three callbacks that are used while processing the transaction:

  • The TransactionStatusUpdated callback provides you with status information throughout the transaction that you need to show to the merchant.
  • The TransactionActionRequired callback informs you that an action, like customer signature, is required for the transaction to continue.
  • The TransactionCompleted callback lets you know that the transaction is finished.

In addition to that, you are also getting an IInteractiveProcess returned, which you can use to abort the transaction and submit a signature if the transaction requires it.

var transactionProcessParameters = new TransactionProcessParameters.Builder().Build(); InteractiveProcess = PosClient.GetTransactionModule().StartTransaction(Device, transactionParameters, transactionProcessParameters, (transaction, transactionProcessDetails, abortable) => { // transaction update information // abortable indicates if the transaction can be aborted in the current state // transactionProcessDetails.Information array indicates human-readable the state information: // always show those two status lines in your merchant-facing UI // transactionProcessDetails.Information[0] // transactionProcessDetails.Information[1] }, (actionType) => { // check for action type if (actionType == Transactions.Actions.ActionType.SIGNATURE) { // submit digital signature. // signature field takes a byte array (byte[]) InteractiveProcess.SubmitSignature(signature, (error) => { // check for error }); // or collect signature on the receipt after transaction InteractiveProcess.SubmitSignatureOnReceipt((error) => { // check for error }); } }, (transaction, transactionProcessDetails, error) => { // check for error if (error != null) { // error indicates that there was a error with the transaction processing // check error.Type and error.Message for more information } else { // Inspect the transaction.Status to get the overall result / transaction completed if (transaction.Status == TransactionStatus.APPROVED) // DECLINED / ABORTED { Console.WriteLine("APPROVED: " + transaction.Identifier); // Save the Transaction.Identifier for later REFUNDs // transaction.Identifier // Provide a printed receipt to the merchant and shopper // transaction.MerchantReceipt // transaction.CustomerReceipt } } });

Making use of status update callback

The transactionProcessDetails.Information[] array of the TransactionStatusUpdated callback will always contain two strings that describe the current state of the transaction.

Make sure to always show those two status lines in your merchant-facing UI.

In case you want to further customize your UI based on the state of a transaction, make use of the details enum that provides fixed workflow steps.

Providing signature in the action required callback

The TransasctionActionRequired callback informs you that an action is required for the transaction to continue. The actionType indicates what type of action the transaction is expecting.

If the actionType is ActionType.SIGNATURE, then you can provide the signature using the IInteractiveProcess that the StartTransaction returned as shown in the code snippet above. You can call SubmitSignature method that accepts a byte array as the digital signature or you can call the SubmitSignatureOnReceipt method if you want to accept signature on the receipt after the transaction is complete.

Aborting a Transaction

You must also allow the merchant to abort a transaction.

To accomplish this, simply make use of the Abort() method on the IInteractiveProcess that was returned when you started the transaction.

After calling the abort method, you should wait not only for the direct callback, but also for the TransactionCompletedcallback of the transaction itself. Aborting a transaction might take a moment, depending on its state. Do not assume that the transaction is over after call the method. There will always be a proper TransactionCompleted callback.

InteractiveProcess.Abort( (status, error) => { //check for error and status });

There are some restrictions when a transaction can be aborted. The card schemes mandate when an abort can be issued, which results in not always being able to abort the transaction.

Pre-Authorizing and Capturing Transactions

You can perform Pre-Authorizations by adding AutoCapture(false) to the TransactionParameters:

var transactionParameters = new TransactionParameters.Builder() .Charge(10.00m, Currency.EUR) .AutoCapture(false) .Build();

To capture an uncaptured transaction later on, you will need to know the transactionIdentifier of the transaction you want to capture. Then simply use the TransactionParameters builder to create a capture object. And similar to the refund, call the AmendTransaction on the ITransactionModule with the created TransactionParameters to start the capture process:

var captureParameters = new TransactionParameters.Builder() .Capture("") .Build();
Was this article helpful?
Dislike 0
Views: 27
Luk menu