API for External Card Issuers

This course describes API for external card issuers in the information system ALIVE Platform. The API is intended for card issuers who issue cards by themselves (digital or plastic including plastic card printing) and would like to communicate with the National Card Database (NCDB) in an automated way. The API allows to manage cardholders, report issued cards or request card issuance (difference is in the card number stock management, see in further chapters) as well as manage card validity, status and a few next attributes. Purpose of this course is to bring a typical example use case, with some pictures, schemes etc. and it hopefully helps you understand the official documentation (download the documentation here)which is written more technically.

Typical way how this API can be used is the integration to school/university inforamtion system. The API can cooperate with university register of students and once a card is issued for a specific student, this card is sent through the API into NCDB.

The API for external issuers works in two modes. The main difference of these modes is who is holder of the stock of serial numbers. Cards.report Using Cards.report mode, holder of the stock of serial number is the school/university. The institution issues a card with specified card number for specified student and only reports to NCDB that card with this particular serial number has been issued. Cards.request Using Cards.request mode, holder of the stock of serial numbers is the ISIC Office. The university only defines through the API that for a specified student, an ISIC (or other card type) should be issued. NCDB then takes automatically one of available serial numbers and assigns it to newly issued card. The assigned serial number is returned in the API response. Important! Before you start a cooperation with a school/university/institution and they want to use the API, always specify on business level the mode they are going to use. Technically, the agreed mode can be set up in card issuer profile within NCDB. In card issuer edit mode, select „External issuer“ and from the drop-down menu, choose either Report mode or Request mode. Only one mode can be chosen!

Open

The following schema describes basic workflow of the API:

Open

Basically, the main steps in using the API are:

• Authentication

• Creating cardholder

• Adding photo for cardholder

• Issuing card

These steps are performed using different API’s endpoints (see further lessons).

Endpoint POST Authenticaton.authenticate When using the API, at first you need to authenticate to get your Bearer Token. Once obtained, the token is valid for 5 minutes (300 seconds) and needs to be attached to every subsequent request. After the validity of the token ends, new token needs to be generated. It is recommended to ask for a new token before every set of the API requests. This way, you can be sure that all data sent through the API are secured. For getting the token, use the endpoint POST Authentication.authenticate and send the credentials you obtained from your ISIC authority (apiGatewayUsername and apiGatewayPassword). The request looks as follows:

Endpoint POST Cardholders.set Through the Cardholders.set endpoint, you can create new cardholder or you can update an existing one. Through one request, only one cardholder can be created/updated. The parameters, enums etc. that can be sent through the request are listed in detail in the official documentation, below, we will focus on some specifics to understand this endpoint. cardholder_id In case you don’t send “cardholder_id“ parametr throught the request, new cardholder is created. In case you send “cardholder_id“, cardholder with this ID within NCDB is updated. In case you are going to update an existing cardholder, you need to send ALL its data again (including the data that are already saved for this cardholder!). legal_representatives The array of data for legal_representative needs to be sent when creating/updating cardholder in case the cardholder is younger than defined age (this age differs for every country based on the local legal directives). Please ask your ISIC ER what is this age for your country. In case the cardholder is younger than defined age and the data for legal representative are not sent, the API returns a validation error. custom_fields The API brings new concept of custom fields that can be defined differently for every card issuer. Through custom fields, basically any value or more values can be attached to a specific card holder or card. This can be for example name of study course, student ID, blood group, card serie etc. Custom fields should reflect “real world” – information that are tied to a person should be bound to cardholders, whereas information tied to card should be defined as card bound. Where to define custom fields? Custom fields can be defined in NCDB -> Cards Issuers -> Custom Fields

When creating a new custom field, several things need to be defined:

Field Name – use some self explanatory name

Field key – this key is used as the identifier in the API request. Use only English letters, without spaces

Bound to – Bound to Card or Bound to Card Holder. This means to which entity the custom field is assigned. Values for Card Holder Bound custom fields need to be sent through POST Cardholders.set endpoint, whereas Card bound custom fields must be sent when the card is issued through POST Cards.report or POST Cards.request

Active – without selecting this checkbox, the custom field can’t be used

Optional – custom fields can be mandatory or optional

CCDB export – sometimes you need the custom field to be exported into CCDB, sometimes it’s enough to save value for custom field within NCDB and no export is necessary

Anonymize – when the cardholder or card are anonymized, should also value for the custom field be removed?

Further, you need to define for which card issuers the custom field should be used. One custom field can be assigned to more card issuers, and also every card issuer can have more custom fields assigned. Use the integrated whisperer to help you find correct card issuer from the list.

AGENT x INSTITUTION The request for endpoint POST Cardholders.set slightly differs based on the fact if the card issuer is an institution or an agent. Institution means that card issuer is school/university and issues cards only for its students. Agent means that card issuer can issue cards for more different institutions. For example, a college that issues cards for students from different schools. In this case, in NCDB, the card issuer needs to have the checkbox “Agent” in “Roles” box allowed.

If card issuer is an Agent, parameter institution_id (in case the institution is chosen from NCDB) or institution_name (in case the institution is NOT from NCDB) needs to be added into POST Cardholders.set request.

POST Cardholders.setPhoto Endpoint for adding a photo for an existing cardholder with specific cardholder_id. POST Cardholders.anonymize When a cardholder asks you to anonymize all his/her personal data according to GDPR, use this endpoint and sent cardholder_id of particular cardholder, for who the data should be anonymized. GET Cardholders.list This endpoint returns information about all cardholders, based on parameters sent as part of the URL. The limit parameter is mandatory (the API returns an error when limit is not present), other parameters are optional. The following ones can be useful for you:

first_name

last_name

date_of_birth

email

modified_from – returns all cardholders modified after specified date and time.

As a result, the URL with parameters can look for example as follows:

The endpoint returns all information for specific cardholder, identified through cardholder_id. GET Cardholders.getPhoto The endpoint returns photo (raster file) of specific cardholder, identified through cardholder_id.

REPORTING CARDS

The following endpoints are designed for issuing/updating cards. Through one request, only one card can be issued/updated. Note: Smart technologies concept As the name suggests, smart_technologies is an array that was designed to save values with some additional technical value. In the first phase of this API development, only values for electronic chips integrated inside cards can be sent through the request (smart technologies support values for EM-Marine and Mifare chips, see the official documentation). For future, more possibilities will be added. POST Cards.report As mentioned earlier, every external issuer can work either in “Report” or in “Request” mode. For report mode (when the stock is completely managed by card issuer), the serial number (parametr “number”) needs to be send as part of the request:

{

"cardholder_id": 198484,

"number": "S420001028374H",

"type": "ISIC",

"form": "DIGITAL_PLASTIC",

"valid_from": "2020-09-01",

"valid_to": "2021-12-31",

"custom_fields": [

{

"name": "customfield4",

"value": "009"

}

]

}

The card design is assigned automatically, based on the design of card range for sent serial number. POST Cards.request For “request” mode, the serial number is not sent through the request, it is assigned automatically based on parameter “design”. NCDB just takes automatically one of available serial numbers with specified design and returns the serial number as part of the response. If parameter “design” is not sent, NCDB takes card issuer’s default design. Of course, there must be some available serial numbers (from “External Issuer” serial range). If not, the request cannot be successfully performed and no card is issued. Sample requests can be found in the documentation. AGENT x INSTITUTION Similiar to what has been mentioned for cardholders, the requests POST Cards.report/POST Cards.request also slightly differ based on the fact whether the card issuer is Institution or Agent. If it’s agent, you need to add one of the following parameters into the request:

institution_id (id of an institution, if this institution is from NCDB)

institution_name_line_1 or institution_name_line_2 (if the institution is NOT from NCDB)

POST Cards.update Through POST Cards.update, you can update smart technologies and custom fields. Please note that it’s not possible to update other properties through this endpoint.   POST Cards.changeValidity Card validity extension. The end of card validity will be replaced by new date. In case the plastic card was issued and its validity can be extended, both digital and plastic card validities will be extended. It is not possible to shorten card validity. Please note that card validity can be changed only in accord to validity cycles allowed for your market.   POST Cards.changeStatus Using POST Cards.changeStatus, you can chnage status of a card. If you issue new cards, its status is ACTIVE. In case you want to deactivate a card, just put it into CANCELLED status. Use the following request:

Cancelled card can be activated again. In case you made some kind of mistake when issuing the card and you need to return the issued card and use the same serial number again, use RETURNED. In case of card return, former card will be locked for any future changes. Card number will become available for new usage. Possible status changes are illustrated by the following schema:

Cards.issuePlastic In case the card form is DIGITAL, you can print also the plastic card and report it into NCDB through POST Cards.issuePlastic endpoint. Once done, the button for printing the card also appears in card detail in NCDB. Through the request, you also specify the design of plastic card (can be different from the design of digital card). You can also sent smart_technologies through this endpoint. The request can look for example as follows:

{

"card_id": 78273,

"design_plastic": "SA-420-787",

"valid_to_plastic": "2021-12-31",

"smart_technologies": [

{

"type": "CONTACTLESS_MIFARE",

"value": "00126"

},

{

"type": "CONTACTLESS_EM_MARINE",

"value": "36984"

}

]

}

GET Cards.list The endpoint returns information of all cards based on sent parameters. Parameter “limit” is mandatory, the others are optional. The following parameters can be useful for you:

cardholder_id – only cards for cardholder with specified id

status – the API returns only cards in desired status

type – card type (returns only ISIC/ITIC/IYTC cards)

modified_from – returns all cards modified after specified date and time

limit – mandatory parameter. It tells how many records will be listed in the response

GET Cards.get The endpoint returns all information about a card defined through its card_id in query parameter.

In this section, let’s have a look at a typical use case how the API can be used. Imagine the following situation: University called “Uni College” wants to use the API for external issuers. Uni College is going to issue cards only for its own students. Uni College holds the stock of serial numbers, prints plastic cards on its own and takes care about the evidence which number has already been used. For each student, specific custom field with course shortcut should be assigned. Which steps should be taken? At first, a card issuer in NCDB should be set up. Go into NCDB -> Card Issuers -> Issuer List and create new card issuer. In Basic details, check “External Issuer” and choose “Report method” (becuase Uni College holds the stock on its own and only “reports” issued cards).

n Roles window, choose correct role and don’t check “Agent” (Uni College is going to issue cards only for its own students, so its mode is “Institution”, not “Agent”). Custom fields As mentioned, Uni College wants to add special information for each student. In NCDB, go to Card Issuers -> Custom Fields and click “New Custom Field” button. Define custom field name, field key, length. Select “Card Holder”, because course name (that will be saved into this custom field) is by its nature bound to cardholder.

At the bottom of the form, assign the field to Uni College in the list of card issuers. Serial numbers Next thing that needs to be done is creating new serial range of type “External Issuer” for Uni College into NCDB (with correct design) and send these serial numbers to Uni College staff. Creating a cardholder For creating a cardholder, you can use the following example request. Note that data for legal representative is sent, because the cardholder is younger than legal age (for the Czech Repoublic, younger than 16 years). Also note the custom field“unicollegecardholder” that we defined earlier:

{

"academic_degree_before_name": "Mgr.",

"first_name": "Jacob",

"last_name": "Newton",

"date_of_birth": "2006-11-18",

"birth_number": "001118/0015",

"gender": "MALE",

"email": "test027@test.cz",

"phone_number": "123456789",

"language": "cs",

"class_name": "7.C",

"grade": 8,

"roles": {

"student":true,

"graduate":null

},

"student_status": "FULL_TIME",

"addresses": [

{

"type": "REGISTERED",

"address_line_1": "Husova 1204/2a",

"address_line_2": "V Tower, 2. patro",

"city": "Praha 6",

"district": "Hlavní město Praha",

"postal_code": "16000"

}

],

"legal_representatives": [

{

"type": "MOTHER",

"academic_degree_before_name": "Ing.",

"first_name": "Jane",

"last_name": "Newton",

"academic_degree_after_name": "MBA.",

"date_of_birth": "1972-01-09",

"birth_number": "720109/0017",

"gender": "FEMALE",

"email": "jana.janikova3@test.cz",

"phone_number": "+420123456789",

"language": "cs",

"addresses": [

{

"type": "REGISTERED",

"address_line_1": "Husova 1204/2a",

"address_line_2": "V Tower, 2. patro",

"city": "Praha 6",

"district": "Hlavní město Praha",

"postal_code": "16000",

"country": "CZE"

}

]

}

],

"custom_fields": [

{

"name": "unicollegecardholder",

"value": "tech012"

}

]

}

As a response, the API returns the following successful result:

{

"message": "OK",

"data": [

{

"cardholder_id": 198503,

"institution_id": 11042,

"gender": "MALE",

"email": "test027@test.cz",

"language": "cs",

"grade": 8,

"roles": {

"student":true

},

"addresses": [

{

"type": "REGISTERED",

"city": "Praha 6",

"district": "Hlavní město Praha",

"postal_code": "16000",

"address_line_1": "Husova 1204/2a",

"address_line_2": "V Tower, 2. patro"

}

],

"legal_representatives": [

{

"type": "MOTHER",

"email": "jana.janikova3@test.cz",

"birth_number": "720109/0017",

"first_name": "Jane",

"last_name": "Newton",

"phone_number": "+420123456789"

}

],

"custom_fields": [

{

"name": "unicollegecardholder",

"value": "tech012"

}

],

"birth_number": "001118/0015",

"first_name": "Jacob",

"last_name": "Newton",

"phone_number": "123456789",

"date_of_birth": "2006-11-18",

"academic_degree_before_name": "Mgr.",

"student_status": "FULL_TIME",

"class_name": "7.C"

}

]

}

Note parameter “cardholder_id: 198503” in the response. This ID will be needed to indentify this cardholder in further requests. The cardholder can also already be found in NCDB. So far, there is no card assigned to this cardholder:

As next step, add photo for cardholder with ID=198503. Let’s have a look at cURL file. As you can see, the script contains URL for the API endpoint, as well as ID of our cardholder and localization of the photo:

$curl = curl_init();

curl_setopt_array($curl,

array

(

CURLOPT_URL => 'https://api.test.aliveplatform.com/v1/cardholders.setPhoto',

CURLOPT_RETURNTRANSFER =>true,

CURLOPT_ENCODING => '',

CURLOPT_MAXREDIRS => 10,

CURLOPT_TIMEOUT => 0,

CURLOPT_FOLLOWLOCATION =>true,

CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,

CURLOPT_CUSTOMREQUEST => 'POST',

CURLOPT_POSTFIELDS =>array('cardholder_id' => '198503','photo'=>new CURLFILE('/C:/Users/lukas.vit/Files/OO2_size/450_540.jpg')),

));

$response = curl_exec($curl);

curl_close($curl);

echo $response; As a response, the API returns only short “OK message”:

{

"message": "OK",

"data": []

}

In NCDB, in the edit mode of our card holder, the photo is already uploaded:

Issue a card Now, in NCDB, there is a cardholder with photo and as last step, we want to report an issued card for this cardholder. As Uni College uses “Report” method, it is necessary to send serial number through the request:

{

"cardholder_id": 198503,

"number": "S420001028294R",

"type": "ISIC",

"form": "DIGITAL_PLASTIC",

"valid_from": "2020-09-01",

"valid_to": "2021-12-31"

}

As a response, the API returns all information about the card:

{

"message": "OK",

"data": [

{

"card_id": 78310,

"cardholder_id": 198503,

"type": "ISIC",

"number": "S420001028294R",

"smart_technologies": [],

"form": "DIGITAL_PLASTIC",

"status": "ACTIVE",

"valid_from": "2020-09-01",

"valid_to": "2021-12-31",

"valid_to_plastic": "2021-12-31",

"institution_id": 11042,

"design": "SA-420-787",

"design_plastic": "SA-420-787",

"institution_name_line_1": "Uni College"

}

]

}

If you check NCDB, the card already exists in the list of issued cards. And this is basically the last step of the whole process, described in its most simple and straightforward version.