Getting Started

Choose your stack (see Supported Programming Languages):

Environment

  1. Connect the NFC reader (see Supported NFC Readers) to your development machine.
  2. Get Zadig, a generic USB drivers installer. Download Here.
  3. You'll need to build libusb.
    sudo apt-get install libusb-1.0-0-dev

    You can get more information here.
  4. Get Card Reader SDK for from GitHub. Download Here. Download Here. Download Here. Download Here. Download Here. Download Here. Download Here.
  5. Import the SDK library to your project.
Make sure your host is connected to the internet. Your host should allow DNS resolving and HTTP(s) traffic to "api.cards.app" (see Network Requirements).

Code Example

  1. Start by creating a ReaderSettings instance:

    //Create reader settings
    ReaderSettings readerSettings = new ReaderSettings()
    {
        DeviceName = "ACS - ACR122U PICC Interface"
    };
    'Create reader settings
    Dim readerSettings As New ReaderSettings() With {
        .DeviceName = "ACS - ACR122U PICC Interface"
    }
    //Create reader settings
    ReaderSettings ^ readerSettings = gcnew ReaderSettings("ACS - ACR122U PICC Interface");
    //Create reader settings
    ReaderSettings readerSettings("ACS - ACR122U PICC Interface");
    You need to provide the NFC device USB name. In this example you can see we provided the default "ACS - ACR122U PICC Interface" for the certified ACR122U device.
    You can easily check the correct NFC device USB name by running GetDevicesNames().

  2. Set your reader credentials. Create a ReaderCredentials instance:

    //Create reader credentials
    ReaderCredentials readerCredentials = new ReaderCredentials()
    {
        ApiKey = "ABCDE1234ABCDE1234ABCDE1234" //This API key is provided by Cards
    };
    'Create reader credentials
    'This API key is provided by Cards
    Dim readerCredentials As New ReaderCredentials() With {
        .ApiKey = "ABCDE1234ABCDE1234ABCDE1234"
    }
    //Create reader credentials
    ReaderCredentials ^ readerCredentials = gcnew ReaderCredentials("ABCDE1234ABCDE1234ABCDE1234");
    //Create reader credentials
    ReaderCredentials readerCredentials("ABCD1234ABCD1234ABCD1234ABCD1234");
    Get your API key using card dashboard (see Card Management). Go to Settings page and click on Generate API key.
    Safely store your API key and do not share it with anyone.

  3. Great! 😎 you've finished initializing the reader settings and credentials. Now we'll create the main CardReader instance. This instance is in charge of communicating with both the reader and the Cards NFC Gateway API.
    Create a CardReader instance and provide both settings and credentials.

    //Create a card reader
    CardReader cardReader = new CardReader(readerSettings, readerCredentials);
    'Create a card reader
    Dim cardReader As New CardReader(readerSettings, readerCredentials)
    //Create a card reader
    CardReader ^ cardReader = gcnew CardReader(readerSettings, readerCredentials);
    //Create a card reader
    CardReader cardReader(readerSettings, readerCredentials);

  4. Subscribe to CardTap event with your own handler method. This event will be raised upon card tap on the NFC reader and will provide you with the wallet owner user ID. In this example, HandleCardTap is the method (event handler) we want to invoke each time a user taps his phone on the NFC reader.

    //Subscribe to Card Tap event
    cardReader.OnCardTap += HandleCardTap;
    'Subscribe to Card Tap event
    AddHandler cardReader.OnCardTap, AddressOf HandleCardTap
    //Subscribe to Card Tap event
    cardReader->OnCardTap += gcnew Cards::CardTapHandler(HandleCardTap);
    //Subscribe to Card Tap event
    cardReader.OnCardTap = HandleCardTap;

  5. Write your own CardTap event handler method. In this example we call it HandleCardTap. Note that the only event argument is a CardTapResponse instance.

    /// <summary>
    /// Handle Card Tap event. This event is raised when a user taps his phone on the reader. 
    /// Note that Cards must be installed on the phone.
    /// </summary>
    public static void HandleCardTap(CardTapResponse cardInfo)
    {
        if (!cardInfo.IsSuccess)
        {
            throw new Exception(string.Format("Failed reading card, error: [{0}] {1}", (int)cardInfo.Error, cardInfo.Error.ToString()));
        }
    
        Console.WriteLine(string.Format("Card read, user ID: '{0}'.", cardInfo.CardDetails.UserID));
    
        //Your code goes here!
        //Do whatever you want with the accepted User ID!
    
        //-----------------------
        //Example: Open the door, if the user is authorized
        //-----------------------
        /*if (YourSystem.IsAuthorizedToOpenDoor(cardInfo.CardDetails.UserID, Doors.Hallway))
        {
            YourSystem.OpenDoor(Doors.Hallway);
        }
        */
    
        //-----------------------
        //Example: Remove balance
        //-----------------------
        /*
            YourSystem.Users.ChangeBalance(cardInfo.CardDetails.UserID, -10);
        */
    }
    ''' <summary>
    ''' Handle Card Tap event. This event is raised when a user taps his phone on the reader. 
    ''' Note that Cards must be installed on the phone.
    ''' <summary>
    Sub HandleCardTap(cardInfo As CardTapResponse)
        If Not cardInfo.IsSuccess Then
            Throw New Exception(String.Format("Failed reading card, error: [{0}] {1}", CInt(cardInfo.Error), cardInfo.Error.ToString()))
        End If
    
        Console.WriteLine(String.Format("Card read, user ID: '{0}'.", cardInfo.CardDetails.UserID))
    
        'Your code goes here!
        'Do whatever you want with the accepted User ID!
    
        '-----------------------
        'Example: Open the door, if the user is authorized
        '-----------------------
        'if (YourSystem.IsAuthorizedToOpenDoor(cardInfo.CardDetails.UserID, Doors.Hallway))
        '{
        '   YourSystem.OpenDoor(Doors.Hallway);
        '}
        '            
    
    
        '-----------------------
        'Example: Remove balance
        '-----------------------
        '
        'YourSystem.Users.ChangeBalance(cardInfo.CardDetails.UserID, -10);
        '            
    
    End Sub
    /// <summary>
    /// Handle Card Tap event. This event is raised when a user taps his phone on the reader. 
    /// Note that Cards must be installed on the phone.
    /// </summary>
    void HandleCardTap(CardTapResponse ^ cardInfo)
    {
    	if (!cardInfo->IsSuccess)
    	{
    		throw gcnew Exception(String::Format("Failed reading card, error: [{0}] {1}", (int)cardInfo->Error, cardInfo->Error.ToString()));
    	}
    
    	Console::WriteLine(String::Format("Card read, user ID: '{0}'.", cardInfo->CardDetails->UserID));
    
    	//Your code goes here!
    	//Do whatever you want with the accepted User ID!
    
    	//-----------------------
    	//Example: Open the door, if the user is authorized
    	//-----------------------
    	/*if (YourSystem.IsAuthorizedToOpenDoor(cardInfo.CardDetails.UserID, Doors.Hallway))
    	{
    	YourSystem.OpenDoor(Doors.Hallway);
    	}
    	*/
    
    	//-----------------------
    	//Example: Remove balance
    	//-----------------------
    	/*
    	YourSystem.Users.ChangeBalance(cardInfo.CardDetails.UserID, -10);
    	*/
    }
    /// <summary>
    /// Handle Card Tap event. This event is raised when a user taps his phone on the reader. 
    /// Note that Cards must be installed on the phone.
    /// </summary>
    void __stdcall HandleCardTap(CardTapResponse cardInfo)
    {
    	if (!cardInfo.IsSuccess)
    	{
    		std::cout << "Failed reading card, error code: " << cardInfo.Error << std::endl;
    	}
    	else
    	{
    		std::cout << "Card read, user ID: " << cardInfo.CardDetails.UserID << std::endl;
    
    		//Your code goes here!
    		//Do whatever you want with the accepted User ID!
    
    		//-----------------------
    		//Example: Open the door, if the user is authorized
    		//-----------------------
    		/*if (YourSystem.IsAuthorizedToOpenDoor(cardInfo.CardDetails.UserID, Doors.Hallway))
    		{
    		YourSystem.OpenDoor(Doors.Hallway);
    		}
    		*/
    
    		//-----------------------
    		//Example: Remove balance
    		//-----------------------
    		
    		//YourSystem.Users.ChangeBalance(cardInfo.CardDetails.UserID, -10);
    	}
    }

  6. Subscribe to StatusChange event with your own handler method. This event will be raised upon any change of the NFC reader status (connection, disconnection etc.). In this example, HandleStatusChange is the method (event handler) we want to invoke each time a status change occurs.

    //Subscribe to Status Change event
    cardReader.OnStatusChange += HandleStatusChange;
    'Subscribe to Status Change event
    AddHandler cardReader.OnStatusChange, AddressOf HandleStatusChange
    //Subscribe to Status Change event
    cardReader->OnStatusChange += gcnew Cards::StatusChangeHandler(HandleStatusChange);
    //Subscribe to Status Change event
    cardReader.OnStatusChange = HandleStatusChange;

  7. Write your own StatusChange event handler method. In this example we call it HandleStatusChange. Note that the only event argument is a CardTapResponse instance.

    /// <summary>
    /// Handles reader status change. 
    /// </summary>
    public static void HandleStatusChange(ReaderStatus readerStatus)
    {
        switch (readerStatus)
        {
            case ReaderStatus.Disconnected:
                Console.WriteLine("Card reader has been disconnected!");
                break;
            case ReaderStatus.Connected:
                Console.WriteLine("Card reader has been connected!");
                break;
        }
    }
    ''' 
    ''' Handles reader status change. 
    ''' 
    Sub HandleStatusChange(readerStatus As ReaderStatus)
        Select Case readerStatus
            Case ReaderStatus.Disconnected
                Console.WriteLine("Card reader has been disconnected!")
                Exit Select
            Case ReaderStatus.Connected
                Console.WriteLine("Card reader has been connected!")
                Exit Select
        End Select
    End Sub
    /// <summary>
    /// Handles reader status change. 
    /// </summary>
    void HandleStatusChange(ReaderStatus readerStatus)
    {
    	switch (readerStatus)
    	{
    	case ReaderStatus::Disconnected:
    		Console::WriteLine("Card reader has been disconnected!");
    		break;
    	case ReaderStatus::Connected:
    		Console::WriteLine("Card reader has been connected!");
    		break;
    	}
    }
    /// <summary>
    /// Handles reader status change. 
    /// </summary>
    void __stdcall HandleStatusChange(ReaderStatus readerStatus)
    {
    	switch (readerStatus)
    	{
    	case ReaderStatus::Disconnected:
    		std::cout << "Card reader has been disconnected!" << std::endl;;
    		break;
    	case ReaderStatus::Connected:
    		std::cout << "Card reader has been connected!" << std::endl;
    		break;
    	}
    }

  8. CardReader instance is now fully constructed. You have passed the reader settings, credentials and subscribed to the two most important events.
    Now, tell CardReader to start listening.

    //Start listening!
    cardReader.Listen();
    'Start listening!
    cardReader.Listen()
    //Start listening!
    cardReader->Listen();
    //Start listening!
    cardReader.Listen();

Congratulations 👨‍🎓! Now wait for a client to tap his digital card on the NFC reader.