PaycodeConnect 1.0.2

Installation

dotnet add package PaycodeConnect --version 1.0.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

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 preReadCard is used to determine whether the terminal will read the card number and send it back in the EMVState.ReadCard EMV event status but the caveat is that for NFC payments the PoS terminal will issue a NFC_TAP_AGAIN forcing the user to tap his card/phone twice to execute the payment.

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, Processing, and Success only State is present.

    EMVData { State = EMVState.[CURRENT_STATE] }
  

• For ReadCard both State and Card are populated. This event is only sent when preReadCard argument is set to true.

    EMVData { State = EMVState.ReadCard, Card = "[CREDIT_CARD_NUMBER]" }
  

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

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

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, bool preReadCard)

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

    Node.StartEMV("2.00", false);
  

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

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

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

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

Enums

• EMVState

  The current state of the EMV process.

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