...

This document describes API for Individual Sales Service (also referred to with abbreviation ISS) in the information system ALIVE Platform. API for Individual Sales Service was developed for card issuers (mostly universities) that issue digital only cards by themselves, but the student pays for the card from his/her side through online payment gategateway. The API also allows to manage cardholders, card validity, status and other related parameters.

...

3/ University sends API request for new card issuance or for validty validity extension.

4/ The API returns back URL for a website, where the student (cardholder) puts additional personal data, contact data and pays for the card. Payment gate gateway with several payment method methods is integrated into the whole process.

...

Content Type
• Most of the requests and responses use JSON data format (application/json content-type). Clients should also include request header parameter Accept: application/json to receive correct response data format.
• Images are uploaded using multipart/form-data encoding type. Besides a path to the image stored in the local device (as permanent or temporary file) the request must contain also cardholder_id attribute to identify the cardholder to whom the image is being uploaded. Base64 encoded images are not supported. A direct image data format is also not supported.
• Images are downloaded as general binary data (octet-stream) with appropriate MIME Content-Type header. Base64 encoded images are not supported.

Charset
• All requests should be send sent with UTF-8 charset specified in the header.

...

API Responses

API responses contains contain from HTTP code and response body with pre-defined structure as described below. In case of error the human readable error messages should be used only for debugging purposes and are not meant to be displayed to the end users.

...

{
"message": "OK",
"data": [ {
"token": "<Bearer Token>",
"expires_in": 300
}
]
}

Cardholders

POST /cardholders.set

...

1/ University checks in its internal information system whether the student already has ISIC/ITIC/ALIVE card or whether he had a card in the past. In case the stuednt is not found, the university creates a cardholder using POST /cardholders.set and saves cardholder_id for further usage. Each future action with this cardholder should be called using corresponding cardholder_id. Also, if any personal data regarding this cardholder is updated within school information system during the term, corresponding cardholder should be updated through POST /cardholders.set endpoint, using his cardholder_id.

2/ University uploads photo for a cardholder (optional) using POST /cardholders.setPhoto. This step is not mandatory, the card can be issued also without any photo. In such case, the student needs to proactively upload the photo through mobile ALIVE App to be able to use the digital card.

...

4/ When the order is completed and paid, the student receives email with his /her card number and additional information how to display this card within ALIVE App mobile application. Using it, he /she can activate digital card within mobile ALIVE App.

...

Important: Once a cardholder is created, the university should immediately save its cardholder_id which is returned through the API. Any further operation with the same cardholder should be done using this cardholder_id, not creating anothe one.

How to change validity of existing card

0/ In summer months, the university can offer to its students/teachers/staff the possibility of validity extension. The validity extension should be offere offered only to those who have valid or expired card.

1/ In case the student asks for the card to be revalidated, the university should call POST /cards.selfChangeValidityRequest. Within the response, the URL link is returned. The API returns link for order completion and payment. This link should be displayed/emailed to the student to complete the order for validity extension and to pay for it.

2/ When the order is completed and paid, the validity of digital card is changed automatically.

Basic flow of the process is described in the below diagram:

...

Environments and Credentials

...