The SDK API methods are stateless static methods which can be called any time and in any order by the client. The only prerequisite to calling any of these methods is to first call the Init method supplying an API key as a parameter (Note that the Init method only needs to be called once per application startup, not before every subsequent API call). Failure to call init first will result in a SDK_NOT_INITIALISED error being returned by the other methods.

The method documentation below is non-platform specific, but is applicable across all of the platforms. Specific platform implementation details are listed along with each method

Each card read or rendered by the SDK belongs to a particular card scheme (e.g. the CSCS card scheme). The SDK user will only be able to read or render cards belonging to schemes for which their API key allows access.

As well as the core card data, each card read or rendered by the SDK may also include third party data, or integration data, which may be accessed via the SDK. An example of this would be Skillsight data related to a card from the CSCS scheme. The SDK user will only be able to read integration data for which their API key allows access.

The SDK works in conjunction with an online webservice managed by RPL, and referred to in this document as the Management Service. Some functions of the SDK will not work without online access to the Management Service (e.g. SDK first time registration), wheras other functions can work offline (e.g. card rendering)

Each API call will return a consistent result in the form of SmartcardClientResult, where T is an object containing the specifics of the result.

boolean isSuccess(); //Success/failure status
T getResult(); // Result object - present if isSuccess = true
SmartcardClientError getError(); //May be present if isSuccess = false

This is an error wrapping class shared across all API methods:

public SmartcardClientErrorType ErrorType; // enum defining fixed set of possible error responses. Always set.
public SmartcardClientException Exception  // if set, contains error specifics. May contain inner exceptions.

Types of errors which can occur during an API call:

• System handled error e.g. mandatory input parameter is null
• Unexpected error e.g. NFC failure when card removed from field part way through by the user
• Environmental error e.g. device is offline when Management Server access is required

This section lists the common error responses which may be returned from the SDK methods. In each case an Exception
object may also be returned containing further details. Method-specific error codes are listed against each method. This is an error wrapping class shared across all API methods:

SDK_NOT_INITIALISED //client needs to call Init before calling this api method
MISSING_OR_BAD_PARAMETERS //client request has invalid or missing parameters
OFFLINE //SDK determines that it doesn't have the required connectivity to the server
PROXY_AUTH_REQUIRED //SDK connectivity to the server is being blocked by a proxy. User must supply credentials.
UNAUTHORISED //SDK has been denied access by the server. Please check that you are using the correct API key
SERVER_ERROR //server calls are failing - try again later
SERVER_TIMEOUT //server calls are timing out
INTERNAL_ERROR //general catchall failure message

Init(Context context, InitParams initParams, ISmartcardClientEventHandler taskEvents, Dictionary<String, String> configOptions)

• This method should be called at least once before any other in order to ensure that the SDK is correctly configured and that it can communicate appropriately with the Management Server. It is responsible for maintaining the SDK's local cache of the data required to read and render cards of various schemes.

• The first ever call to Init will register the SDK instance with the Management Server. If this initial registration fails for whatever reason, none of the other API calls will be available

• Subsequent calls to Init will refresh the existing scheme info (add, edit and delete) following updates commissioned on the server for this client

• Failure to update or add a scheme will NOT stop the SDK from being initialised i.e. user can continue to use the app despite being out-of-date or missing a new scheme configuration

• Executes asynchronously with a callback for progress and completion (platform specific)

• Cards for any given scheme will not be readable by the SDK until all relevant scheme information has been downloaded

This is a platform specific context which allows the SDK to perform operations based on the runtime environment, e.g. in order to create and access a local store. See platform specific notes below for more details.

• apiKey The API key is issued to the application developer by RPL, and is owned and stored by the calling application. N.B. It is important that it should be held securely by the app e.g. in a secure data store, as misuse of the key by third parties may lead to it being deactivated (see below)

• appIdentifierName Owned and stored by the calling app. RPL will supply this to the app developer along with their api key.

• appVersion This is a required parameter and is expected as a semantic version number in the form x.x.x. (major.minor.patch) This is checked against the minimum acceptable application version number as determined by the Management Sserver, and will cause the SDK initialisation to fail if it is too low or incorrectly formatted

• appFriendlyName Allows each app instance to have a friendly label which can be used later for easy identification of card reader devices e.g. Site Hut 1. If the app provides a mechanism for the user update their name then the new name may be passed in via this parameter.

Flexible structure for passing implementation specific values required by different platforms and / or apps. Each platform may support different options here, but the following options are supported by all

• force-reset Deletes ALL scheme configuration data, images and integrations, then re-registers the device. In most cases, this action will likely require a restart of the calling app. This feature should only be required where the app has become unstable due to bad configuration data.

• proxy-url

• proxy-port

• proxy-user

• proxy-password

(.Net version only) Network proxy details required for the SDK to access its back-end servers

This is an optional callback parameter which will pass progress information back to the caller for debugging purposes. Implementation is platform specific.

The result of the call is returned via a result object of type SmartcardClientResult, which is defined as follows:

public Long timeDriftMS; // difference in milliseconds between the device and server clocks - null if unknown
public Long timeDriftThresholdSeconds;// acceptable drift in seconds before SDK recommends displaying a warning - null if unknown
public String desiredAppVersion; // latest app version supported by the Management Service. Can be used by the caller to inform the user to upgrade.
public String requiredAppVersion; // minimum app version supported by the Management Service. Can be used by the caller to inform the user that the need to upgrade.
public enum versionStatus; // Indicates status of the app version supplied. Can be in one of 3 states : OK, SHOULD_UPGRADE or MUST_UPGRADE
public InitException initException; // reports passive issues which occurred during initialisation which did not prevent the SDK from initialising e.g. server unavailable. 

The following error types are specific to this method. In each case an Exception object may also be returned containing further details. INIT_APP_VERSION_IS_OUT_OF_DATE //The application version is disallowed by the server as it is too low

Platform specific notes:

• .Net
• android

ReadCard(IReadCardTaskEvents taskEvents, ReadCardTaskParams readCardTaskParams, EnumSyncOption syncOptions)

• This method allows the user to read data from a JCOP compliant physical smartcard via NFC

• Connectivity with the card is established by the calling application, and the relevant connection object is passed into this method as a parameter

• Executes asynchronously with a callback for progress and completion (platform specific)

• Cards for any given scheme will not be readable by the SDK until all relevant scheme information has been downloaded

This option allows the caller to specify if the data on the card will be synchronised with the online Management Service before the data is returned. Doing so will ensure that the card data is correct and up to date.

This has three possible states:

SYNC - (Default option) if possible then the card data will be synced with the server before the read is performed 
NO_SYNC - No card data sync is attempted, so card data will be read directly from the card and returned 
SYNC_ONLY - Only the card sync will be attempted, with no card data being returned

This parameter is used to supply the platform specific connection object through which the SDK will communicate with the card.

• reader .NET only - an instance of PCSC.SCardReader which has established connectivity with the card

• intent Android only - an instance of an NFC Intent triggered by a card read

This is an optional callback parameter which will pass progress information back to the caller for debugging purposes. Implementation is platform specific.

The result of the call is returned via a result object of type SmartcardClientResult, which is defined as follows:

public CardData cardData; //Will be null if syncOptions = SYNC_ONLY
public bool cardSynced;  // Flag to indicate if the card data has been synchronised with the server. Will be false if syncOptions = NO_SYNC or if the sync fails for some reason.
public SmartcardClientException cardSyncException  // Details on why the sync failed (if sync was requested)
public SchemeIntegrationReadException SchemeIntegrationReadException  // details any integration read failures e.g. failed to get skillsight data

Card data will be returned as a generic language-specific object (i.e. a POCO in C#, POJO in Java etc) in the following form

class CardData
{
    CardDataScheme Scheme;
    List<CardDataIntegration> Integrations;
}

class CardDataScheme
{
    string Identifier; //Scheme Id, e.g. 'cscs'
    List<CardDataBlock> DataBlocks;
}

class CardDataBlock
{
    int Index;    //Specifies position of data block on a physical card 
    string Type;  //Specifies the MIME type of data expected in the data block, e.g. application/json or image/jpeg. Type for the pseudo-XML on a CSCS card is text/sml
    string Data;  //Base64 encoded data
}

class CardDataIntegration //Holds additional data for related schemes, e.g. SkillSight
{
    public string Identifier;
    public List<CardDataBlock> DataBlocks;
}

The following error types are specific to this method. In each case an Exception object may also be returned containing further details.

READ_CARD_ERROR //Unrecoverable error occurred whilst reading or writing data to the card
READ_CARD_UNKNOWN_CARD //Card is not recognised by the SDK and cannot be read
READ_CARD_UNKNOWN_SCHEME //Card is readable, but the card scheme is not available to this SDK instance
READ_CARD_NOT_SUPPORTED //Scheme config does not contain an appropriate script for the hardware type
READ_CARD_SCHEME_CONFIGURATION_ERROR  //Scheme config  missing some data needed to read the card

Platform specific notes:

• .Net
• android

ReadCardByQRCode(ReadCardByQRCodeParams readParams, TaskEvents taskEvents)

• This method allows the user to read card data from a QR code generated by RPL's Vircarda app

• Online connectivity with the Management Server is required for full functionality. Only basic validation may be done in offline mode

• Executes asynchronously with a callback for progress and completion (platform specific)

• It is the application developer's responsibility to recognise and acquire the text from a QR read via whatever mechanism is available on their platform.

• qrCodeString The QR code text as read via the applications camera or other QR scanning device
• cardReadInfo Additional data pertaining to the read which can be used in Vircarda. See below for details
• forceOfflineMode If set to true then the SDK will behave as if it is offline i.e. it won't call the Vircarda Server to verify the QR code

public Date cardReadSwipeDateTime //App date and time when the read occurred
public String readerName   //Friendly name for the reading application - will be displayed in Vircarda
public String locationName //(optional) Location name for the read location
public double longitude    //(longitude)Longitude of the read location
public double latitude     //(latitude) Latitude of the read location
public String dataTag      // For future use

This is an optional callback parameter which will pass progress information back to the caller for debugging purposes. Implementation is platform specific.

The result of the call is returned via a result object of type SmartcardClientResult, which is defined as follows:

public enumQRCodeResult resultCode // enum specifying result status. See below
public CardData cardData;  //See ReadCard for definition of CardData
public String rejectedMessage; //Text description of rejection reason (if any)
public String qrCodeString; // The QR text as originally passed in. May be required for OFFLINE reads where the calling app may wish to re-present the code at a later date.
public QRCodeMemberInfo qrCodeMemberInfo;// Basic QR information, available in OFFLINE mode. See below for details

SUCCESS         // Everything is good
QRCODE_EXPIRED  // QR code was generated too long ago
OFFLINE         // SDK cannot validate QR with Vircarda. QR can be tried again later
TIMEOUT         // controlled retry (with delay, failing after X attempts or X days)
SERVER_REJECTED // Vircarda rejected the QR code - see rejectedMessage for details
RETRY_LATER     // Vircarda server is currently unable to fulfil the request.
SERVICE_ERROR   // Vircarda server is currently down 

public String cardNumber;
public String cardScheme; 
public String cardHolder;

The following error types are specific to this method. In each case an Exception object may also be returned containing further details.

READ_CARD_ERROR //Unrecoverable error occurred whilst reading or writing data to the card
READ_CARD_UNKNOWN_CARD //Card is not recognised by the SDK and cannot be read
READ_CARD_UNKNOWN_SCHEME //Card is readable, but the card scheme is not available to this SDK instance
READ_CARD_NOT_SUPPORTED //Scheme config does not contain an appropriate script for the hardware type
READ_CARD_SCHEME_CONFIGURATION_ERROR  //Scheme config  missing some data needed to read the card

Platform specific notes:

• .Net
• android

RenderCard(RenderCardParams renderParams, TaskEvents taskEvents)

• This method allows the user to render front and back card images

Data to be displayed on the card render is passed in via this parameter. It is anticipated that this will usually originate from a previous call to an SDK card read method.

• schemeId The identifier for the card scheme being rendered
• renderCardDataMap Dictionary / hashmap containing name/value pairs for all the card data. Scheme specific.
• roundingParams Specify the radius of the rounded card corners on the render. May be set to 0 for square corners.

This is an optional callback parameter which will pass progress information back to the caller for debugging purposes. Implementation is platform specific.

The result of the call is returned via a result object of type SmartcardClientResult, which is defined as follows:

public CardFront //Image data (platfrom specific) 
public CardBack  //Image data (platfrom specific)

The following error types are specific to this method. In each case an Exception object may also be returned containing further details.

SCHEME_CONFIG_ERROR //SDK does not have sufficient data locally to render the card. Try calling UpdateSchemeConfig.

Platform specific notes:

• .Net

Card render data is returned as a byte[] in .png format

• android

SDKSchemeList GetSchemeList ()

• Returns summary information about the schemes, integrations and render information currently cached by the SDK.
• Expected use case is for diagnostic purposes

Date lastSyncAttemptDateLocal;           // device local time of last attempted sync 
enumSyncErrorCode lastSyncErrorCode      // contains details if last sync attempt fails - see error codes below
long imageLibraryCount; //Number of locally cached images
public List<SchemeInfo> schemeInfoList; //cached scheme detals
public List<IntegrationInfo> integrationInfoList; //cached integration details

UNAUTHORISED //SDK was not allowed to access the scheme 
CLIENT_ERROR //SDK call failure 
SERVER_ERROR //Management Server failure
SERVER_UNAVAILABLE //Management Server not contactable
OFFLINE //SDK could not connect
INTERNAL_ERROR //Other error occurred

String schemeId
String schemeName
String description
String logoThumbnail            
String logo
String SupportNumber            
int renderItemCount
Date lastServerUpdatedDateUTC            // Date when config was last updated on the server (config or render items)
enumSyncErrorCode lastSyncErrorCode      // if the last sync attempt failed for this scheme, this will be set. 

String integrationId
String integrationName
String description
String logoThumbnail            
String logo
String SupportNumber            
Date lastServerUpdatedDateUTC    // Date when config was last updated on the server.
enumSyncErrorCode lastSyncErrorCode // if the last sync attempt failed for this integration, this will be set. 

Platform specific notes:

• .Net
• android

GetStatus(ISmartcardClientEventHandler taskEvents)

• Returns general connection and status info. Can be called if SDK is not initialised
• Can be used to determine which SDK functions are currently available

This is an optional callback parameter which will pass progress information back to the caller for debugging purposes. Implementation is platform specific.

boolean initialised; //Has init been called
enumConnectionStatus connectionStatus; //See below for possible values
String sdkVersion; //Version number of the SDK

GOOD                // Comms with both the Management Server and Vircarda are good
OFFLINE,            // No internet connectivity connected by the SDK
NO_ONLINE_VIRTUAL,  // Online virtual card reads are unavailable. Physical cards unaffected.
NO_ONLINE_PHYSICAL, // Syncing of physical cards offline. Virtual and offline physical reads unaffected.
UNAVAILABLE,        // No online services available
UNKNOWN             // Other error has occurred

Platform specific notes:

• .Net
• android

UpdateSchemeConfig(ISmartcardClientEventHandler taskEvents)

• Allows the client app to initiate a refresh of all stale schemes in the local cache
• Executes asynchronously with a callback for progress and completion (platform specific)
• No information is returned in response - a follow up call to GetSchemeList can be made to check on the status of any updates made

This is an optional callback parameter which will pass progress information back to the caller for debugging purposes. Implementation is platform specific.

Platform specific notes:

• .Net
• android