Integration guide

                                                     _   
 ___  ___  ___ _   _  ___ ___  _ __  _ __   ___  ___| |_ 
/ __|/ _ \/ __| | | |/ __/ _ \| '_ \| '_ \ / _ \/ __| __|
\__ \  __/ (__| |_| | (_| (_) | | | | | | |  __/ (__| |_ 
|___/\___|\___|\__,_|\___\___/|_| |_|_| |_|\___|\___|\__|

Introduction

Secucard provides several reference implementations for its API (Application Programming Interface), called client SDKs (Software Development Kits). You can download these SDKs as an open source version, ready to be integrated directly into your project. Since you get the full source code to these SDKs, you can extend and alter them as you see fit, or use them to help you better understand the use of the API for your own implementations. These SDKs also come with both a small demo application for quick testing, as well as a full fledged cashier application to see a real world example of Secucard's possibilities. We also provide a readily built binary library, to be used in all those languages and frameworks where we do not yet provide an SDK for.

What follows is an SDK-agnostic explanation of the Secucard ecosystem, explaining general concepts. Each use case is detailed with code snippets for our supported SDKs, to better clarify the abstract concepts you will encounter here. For more detailed information regarding a specific SDK, please refer to its SDK documentation.

General principles of the secuard API and client SDK

The secucard API distinguishes between several products. Examples of such products are: Loyalty, Payment and Prepaid. For every product, its functionality is grouped into resources. For example, the product Loyalty has resources Cards, Checkins and Customers, whereas the product Payment has resources Customers and Transactions:

  • Loyalty (product)
    • Cards
    • Checkins
    • Customers
  • Payment (product)
    • Customers
    • Transactions

Every resource provides the necessary functionality to be managed by the API user. For example, the Loyalty.Cards resource can be queried for a list of cards and assign a user to a certain card. The Payment.Transaction resource can be queried for a list of transactions. Most of this functionality requires the user to be authorized, which means that the user must provide credentials when using specific functionality.

To allow easy use of the API, a client secucard SDK (Software Development Kit) is available for different programming languages. All SDKs provide a client entry point to the API, named SecucardConnect (also known as "the client"). This client exposes a service for each resource, which provides all functionality for that specific resource. Access to these resources is possible using the following semantics:

Client -> Product -> Resource-Service

On top of providing access to resources, certain services also provide event handlers for special events happening during the usage of these resource functions. After registering for these events, the user can be notified of status updates during transactions, customers checking in and many more events. Note that in order to use events, the communication protocol needs to support this.

Provided the the SDKs language supports this, the resource service operates on typed data models instead of raw JSON or XML strings. Model types are generally named similar to its related API resource. The same logical organisation for products also applies to the SDK on source code level, i.e. resource services and their data models are always grouped together in a product package, namespace or similar modularization for the specific platform.

Besides providing access to services, each SDK's client entry point provides the following features:

  • Configuration of the client (API endpoint URLs, timeouts, credentials, ..)
  • Authentication handling
  • Registering callbacks for server connection state changes
  • Dispatching external events (coming from a web hook, for example) to a general or resource-specific event handler

Configuration

The format in which the configuration is defined varies per SDK. All SDKs come with default configuration, so you only have to change the configuration to your needs. The following items can be configured in all SDKs:

  • secucard API endpoint
  • Authentication endpoint
  • Cache instance

Usage of these modules happens through the SecucardConnect class, on which we will elaborate later. It is recommended to first continue with authentication and authorization, which is the first step to using Secucard's services.