PaycodeConnect 1.1.1

Installation

dotnet add package PaycodeConnect --version 1.1.1

Usage

Setup

To create a node in the current machine, we need to call the Setup function on PaycodeConnect

using PaycodeConnectSDK;

PaycodeConnect Node = new PaycodeConnect();

Node.Setup();

Ticket QR

To establish connections between nodes we need to generate and share a ticket between them. The easiest way is to generate a QR and scan it with a Paycode POS Terminal, you can create a base64 encoded QR containing the ticket with PaycodeConnect like so

try
{
    string ticketQR = await Node.GenerateTicketQRCodeBase64Async();
    qrImage.Source = Base64ToImage(ticketQR);
}

// Here is an example base64 to C# Bitmap function
private BitmapImage Base64ToImage(string base64String)
{
    byte[] bytes = Convert.FromBase64String(base64String);
    using (MemoryStream ms = new MemoryStream(bytes))
    {
        BitmapImage bitmapImage = new BitmapImage();
        bitmapImage.SetSource(ms.AsRandomAccessStream());
        return bitmapImage;
    }
}

Authorization

If there is no session in the PoS Terminal we can send an authorization command with the provided Paycode credentials to create a session.

Node.Authorize("[EMAIL]", "[PASSWORD]");

Start EMV

Once connected we can send commands to the POS Terminal, one such command is the startEMV command to start the EMV process. We can also receive data from the POS Terminal, please see [EMVStateChange Event](## EMVStateChange Event) section to see how you can handle incoming EMV data.

The second argument of this function emvType is used to determine which EMV flow to use you can choose between EMVType.Emv for Visa/Mastercard, EMVType.Amex for American Express, or EMVType.Combined to let the PoS auto-detect the card type.

Node.StartEMV("2.00");

ConnectionChange Event

When a remote node connects or disconnects from our current node PaycodeConnect emits a ConnectionChange event, we can listen to these events and handle our app's state accordingly.

PaycodeConnect Node = new PaycodeConnect();

Node.ConnectionChange += (sender, e) =>
{
    myText.Text = $"Connection changed: {e.Connected}";
};

Node.Setup();

EMVStateChange Event

After sending the startEMV command, we can start receiving updates about the EMV process from the PoS Terminal. To receive these updates we can subscribe to the EMVStateChange event.

PaycodeConnect Node = new PaycodeConnect();

Node.EMVStateChange += (sender, e) => 
{
    emvText.Text = $"EMV changed: {e.Data.State}";
};

Node.Setup();

e.Data is of type EMVData and the struct's fields are populated depending on the current EMVState (e.Data.State). Here is what is populated depending on each state:

• For NotStarted, AwaitingCard, and Processing only State is present.

    EMVData { State = EMVState.[CURRENT_STATE] }
  

• For Error three properties are present: State, Message, and Code.

    EMVData { State = EMVState.Error, Message = "Transaction failed", Code = -8019 }
  

• For Success both State and Transaction are populated.

    EMVData { State = EMVState.Success, Transaction = { /* ... */ } }
  

Terminal Scanner

To use the PoS as a barcode scanner we need to set the ScannerPrefixes capability for the Node after we have established a connection.

PaycodeConnect Node = new PaycodeConnect();

Node.ConnectionChange += (sender, e) =>
{
    myText.Text = $"Connection changed: {e.Connected}";
	if (e.Connected)
    {
        Capabilities capabilities = new Capabilities
        {
            ScannerPrefixes = ["cstmprefix"]
        };
        magicNode.SetCapabilities(capabilities);
    }
};

Node.Setup();

And then we can listen for scanner events.

magicNode.TerminalScanner += (sender, e) =>
{
    scannerText.Text = $"Scanned barcode: {e.Content}";
};

API Reference

Properties

• Connected bool

  Flag to know whether a node is currently connected or not.

    Node.Connected
  

• NodeSetup bool

  Flag to know whether the node has been setup. To setup a node call the Setup() function, a node must be setup to use any of the functionality of this library.

    Node.NodeSetup
  

Methods

• void Setup()

  Initializes a node on the current machine. This method must be called before using any other method in PaycodeConnect.

    Node.Setup();
  

• Task<string> GenerateTicketQRCodeBase64Async()

  Generate a base64 encoded QR as a string containing the current node's ticket.

    string ticketQR = await Node.GenerateTicketQRCodeBase64Async();
  

• Task<string> GenerateTicketAsync()

  Generate the raw ticket string for the current node.

    string ticket = await GenerateTicketAsync();
  

• void Authorize(string email, string password)

  Send an authorization command to login into the PoS terminal, if it is already logged in this command will be ignored.

    Node.Authorize("test@test.com", "password")
  

• void StartEMV(string amount, EMVType emvType = EMVType.Combined)

  Send a command to start the EMV process on the connected Paycode PoS Terminal.

    Node.StartEMV("2.00", EMVType.Combined);
  

• void Shutdown(bool restart)

  Disconnect and shutdown the current node completely. To keep using the node's functionality you need to either set the restart flag to true (default false) or call Node.Setup() again.

    Node.Shutdown(true);
  

• void ReconnectToLastNode(bool restart)

  Attempts to connect to the last known node.

    Node.ReconnectToLastNode();
  

• void SetCapabilities(Capabilities capabilities)

  Set a node's capabilities.

    Node.SetCapabilities(capabilities);
  

• void ReverseTransaction(string folio)

  Reverse a specific transaction

    Node.ReverseTransaction(folio);
  

• void PrintTransaction(string folio)

  Print the receipt of a specific transaction. Mostly used for re-prints.

    Node.PrintTransaction(folio);
  

Events

• ConnectionChange

  Triggers whenever a remote node connects/disconnects from our local node.

    public class ConnectionChangeEventArgs : EventArgs
    {
        public bool Connected { get; }
        public ConnectionChangeEventArgs(bool connected) => Connected = connected;
    }
  
    public event EventHandler<ConnectionChangeEventArgs> ConnectionChange;
  

• EMVStateChange

  It is triggered whenever a change in the EMV process occurs from the connected Paycode PoS Terminal and contains EMVData as argument.

    public class EMVStateChangeEventArgs : EventArgs
    {
        public EMVData Data { get; }
        public EMVStateChangeEventArgs(EMVData data)
        {
            Data = data;
        }
    }
  

• TerminalScanner

  Triggers whenever a barcode that contains a prefix set in the node's capabilities is scanned by the PoS.

    public class TerminalScannerEventArgs : EventArgs
  {
      public string Content { get; }
      public TerminalScannerEventArgs(string content)
      {
          Content = content;
      }
  }
  

Structs

• EMVData

  Data sent by the PoS Terminal throughout the EMV process. Data is filled depending on the current EMVState, for example EMVState.Error contains Code and Message but not Transaction.

    public struct EMVData
    {
        public EMVState State { get; set; }
        public int? Code { get; set; }
        public string? Message { get; set; }
    	public Transaction? Transaction { get; set; }
    }
  

• Transaction

  Transaction data received on EMVState.Success

    public struct Transaction
  {
      public string Authorization { get; set; }
      public string Reference { get; set; }
      public string Folio { get; set; }
      public string? Type { get; set; }
      public string? CardBrand { get; set; }
      public string? CardNumber { get; set; }
      public string? Issuer { get; set; }
      public string? Total { get; set; }
      public string? Subtotal { get; set; }
      public string? Tip { get; set; }
      public string? Arqc { get; set; }
      public string? Aid { get; set; }
      public string? Al { get; set; }
      public string? Tvr { get; set; }
      public string? Tsi { get; set; }
  }
  

• Capabilities

  Node capabilities to be set optionally on a connected node.

    public struct Capabilities
  {
      public string[]? ScannerPrefixes { get; set; }
  }
  

Enums

• EMVState

  The current state of the EMV process.

    public enum EMVState
    {
        NotStarted,
        AwaitingCard,
        ReadCard,
        Processing,
        Success,
        Error
    }
  

• EMVType

  The type for the EMV flow that will be used.

    public enum EMVType
    {
        Emv,
        Amex,
        Combined
    }