.NET POS Integration via PayClient

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.




Download

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

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.


Installation

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 (https://www.nuget.org/packages/NLog/, NLog.dll)
  • Json.NET (https://www.nuget.org/packages/Newtonsoft.Json/, Newtonsoft.Json.dll)
  • WebSocketSharp (http://www.nuget.org/packages/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

After adding the PayClient dependencies to your project you are all set to integrate payments. The following will guide you through the steps you will have to implement on your side.

To use this PayClient you need to configure the PayServer to use P3_WEBSOCKET as the server protocol. See the PayServer configuration page for more information.

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.

PosClient = new PosClient(PAY_SERVER_ADDRESS, PAY_SERVER_PORT);

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 Device object 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
              }
          }
    });

More information on the completed transaction statuses and what they mean can be found here.

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.

You can also configure the behavior of Signature action in the PayServer as described in the PayServer configuration page


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 TransactionCompleted callback 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.

Providing a Printed Payment Receipt

Information on creating your own receipts can be found here.

Performing a Refund

Information on how to perform refunds can be found here.

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("<transactionIdentifier>")
    .Build();

Can we help you?

If you cannot find your answer, contact us and we'll get in touch with you soon.

© Copyright 2017 Payworks GmbH. Legal.