PaycodeConnect 1.2.2

Installation

dotnet add package PaycodeConnect --version 1.2.2

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

string ticket = Node.GenerateTicket();
string qr = Node.GenerateQRCodeBase64(ticket);
qrImage.Source = Base64ToImage(qr);


// 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();

PresenceChange Event

Connected nodes are constantly sharing "presence" messages between each other. When these messages stop or restore this event is called. This is also represented in the PoS device with the yellow warning icon.

PaycodeConnect Node = new PaycodeConnect();

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

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 = { /* ... */ } }
  

• For Reversal three properties are present: State, Message, and Code. Where code can be either 0 for success or 1 for error.

    EMVData { State = EMVState.Reversal, Message = "success", Code = 0 }
  

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

• ResultCode Setup(CompletionCallback? callback = null)

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

    Node.Setup();
  
    // with callback
    Node.Setup((resultCode) => {
    	// Check resultCode
    })
  

• DEPRECATED Task<string> GenerateTicketQRCodeBase64Async()

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

    string ticketQR = await Node.GenerateTicketQRCodeBase64Async();
  

• string GenerateTicket()

  Generate the raw ticket string for the current node.

    string ticket = GenerateTicket();
  

• string GenerateQRCodeBase64(string ticket)

  Generate base64 data for rendering a QR from a ticket.

    string ticket = GenerateTicket();
    string qr = GenerateQRCodeBase64(ticket);
  

• ResultCode Authorize(string email, string password, CompletionCallback? callback = null)

  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")
  

• ResultCode Logout(CompletionCallback? callback = null)

  Send a logout command to the PoS to logout of the current user session.

    Node.Logout()
  

• ResultCode StartEMV(string amount, EMVType emvType = EMVType.Combined, CompletionCallback? callback = null)

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

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

• ResultCode Shutdown(bool restart, CompletionCallback? callback = null)

  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);
  

• ResultCode ReconnectToLastNode(CompletionCallback? callback = null)

  Attempts to connect to the last known node.

    Node.ReconnectToLastNode();
  

• ResultCode SetCapabilities(Capabilities capabilities)

  Set a node's capabilities.

    Node.SetCapabilities(capabilities);
  

• ResultCode ReverseTransaction(string folio, CompletionCallback? callback = null)

  Reverse a specific transaction

    Node.ReverseTransaction(folio);
  

• ResultCode PrintTransaction(string folio, CompletionCallback? callback = null)

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

    Node.PrintTransaction(folio);
  

• ResultCode SetPin(PinPayload payload, CompletionCallback? callback = null)

  Set the PIN for authentication in a PoS terminal.

    Node.SetPin(pinPayload);
  

• ResultCode AuthorizePin(string pin, CompletionCallback? callback = null)

  Send an authorization command to login into the PoS terminal with a PIN, a PIN needs to be set first using SetPin.

    Node.AuthorizePin(pin);
  

• public delegate void CompletionCallback(ResultCode code);

  All methods that have an inner async task take this completion callback as argument.

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;
  

• PresenceChange

  Triggers when a node stops sending presence messages, this means we lost connection somehow but we might get it back.

    public class PresenceChangeEventArgs: EventArgs
  {
      public bool Presence { get; }
      public PresenceChangeEventArgs(bool presence) => Presence = presence;
  }
  
    public event EventHandler<PresenceChangeEventArgs> PresenceChange;
  

• 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; }
    	public string? id { get; set; }
    	public bool? lost { 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; }
    	public bool? PingInternetConnectivity { get; set; }
      public bool? ForceRemoteControl { get; set; }
      public bool? DisableManualPayments { get; set; }
  }
  

• PinPayload

    public struct PinPayload
  {
      public string Pin { get; set; }
      public string Password { 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
    }
  

• ResultCode

    public enum ResultCode
  {
      Success = 0,
      StateUnavailable = 1,
      NodeUnavailable = 2,
      RuntimeUnavailable = 3,
      SenderNotAvailable = 4,
      ConnectionTimeout = 5,
      EndpointOnlineTimeout = 6,
      Utf8Conversion = 7,
      IrohEndpointBind = 8,
      IrohJoin = 9,
      GossipApi = 10,
      GossipNet = 11,
      IrohKeyParse = 12,
      Decode = 13,
      Json = 14,
      Anyhow = 15,
      TryLock = 16,
      Nul = 17,
      SetLogger = 18,
      Panic = 999
  }