Server JSON API for non-Keyple clients

Overview

This guide is specifically designed for users who are not currently using Keyple in their terminals, but wish to connect to a Keyple server. It details the JSON data exchange between the terminal and the server, but does not cover the transport of this data.

This allows the development of a distributed solution in which the client reader terminal delegates the entire management of the card transaction to the server.

The diagram below illustrates the architecture of a non-Keyple application installed on a terminal and connected to a server based on Keyple:

Principle

The Keyple remote transaction uses four types of messages exchanged between the terminal and the server in JSON format:

The diagram below shows the global messaging flow:

On its own initiative (e.g. following the detection of a card), the terminal sends to the server a message of type “Execute Remote Service” to ask it to start a card transaction. At this step, the terminal has the ability to tell the server which business service to run and also to provide additional custom input data.

As long as the transaction is not completed, the terminal receives from the server messages of type “Command” containing the actions to be performed with the card or the terminal’s reader. The responses are sent to the server in messages of type “Response”.

When the transaction is complete, the terminal receives from the server a final message of type “End Remote Service” which optionally contains custom transaction output data.

Data structure

Messages are in JSON format and have the following structure:

API specifications

• API 2.1
• API 2.0
• API 1.0

API 2.1

Changelog

This minor version optimizes transaction time by reducing the number of network exchanges. A new field has been added to the “Execute Remote Service” message sent to the server, and the “Reader Type” command received from the server has been removed.

MessageDto

The diagram below shows the structure of the MessageDto object but the detailed content will be described in the sections associated with each message type:

Execute Remote Service

The purpose of this message, sent to the server, is to initiate the server-controlled card transaction.

By using the identification properties provided by the terminal in its subsequent responses, the server ensures consistent and accurate data flow management throughout the entire system.

Following the transmission of this message, the server will return a message of type “Command”, containing the first action to be performed with the card or the terminal’s reader, or of type “End Remote Service” to terminate the transaction.

The following UML class diagram illustrates the structure of this object and may help to implement it in the development language of the target terminal.

MessageDto

ExecuteRemoteServiceBody

Example

{
    "apiLevel": 2,
    "sessionId": "b1b8ed38-bae6-4b2e-a747-67d233652ea9",
    "action": "EXECUTE_REMOTE_SERVICE",
    "clientNodeId": "ca21fd3c-a055-4be5-aad1-c61af3528371",
    "localReaderName": "READER_1",
    "body": "{\"coreApiLevel\":2,\"serviceId\":\"AUTHENTICATE_CARD\",\"isReaderContactless\":true,\"inputData\":{\"userId\":\"7b13592c-0d21-429b-80d2-3dc565338ea3\"}}"
}

Command

The purpose of this message, received from the server, is to ask the terminal to perform a specific service with the card or the terminal’s reader.

There are three types of services potentially requested by the server:

Following the reception of this message, the terminal will send to the server a message of type “Response” containing the response of the operation.

The following UML class diagram illustrates the structure of this object and may help to implement it in the development language of the target terminal.

Card Presence

This service allows the server to know if a card is inserted in the reader.

There are no parameters for this service.

The terminal must then send the response to the server in a message of type “Card Presence (Response)”.

MessageDto

IsCardPresentCmdBody

Example

[
    {
        "apiLevel": 2,
        "sessionId": "b1b8ed38-bae6-4b2e-a747-67d233652ea9",
        "action": "CMD",
        "clientNodeId": "ca21fd3c-a055-4be5-aad1-c61af3528371",
        "serverNodeId": "4132f1ef-4386-49b0-acb6-cc16035c107a",
        "localReaderName": "READER_1",
        "remoteReaderName": "a65f4920-7e96-4082-986a-b58d85978c07",
        "body": "{\"coreApiLevel\":2,\"service\":\"IS_CARD_PRESENT\"}"
    }
]

Card Selection

The primary objective of this service is to establish a logical communication channel with a card.

To enable processing of different card profiles, it offers the creation of selection scenarios with integrated selection cases. The scenario is provided by the server after a card is detected, and it involves checking whether the card is compatible with at least one of the selection cases. The selection cases are processed successively, in the order in which they are defined.

There are several options for executing the scenario:

• the process stops at the first selection case where the card matches, or all scenarios are systematically processed.
• the physical channel can be kept open or closed at the end of each selection case.

A card selection case incorporates various independent filters that can be applied individually or in combination to determine if a detected card is suitable for performing a transaction. While some cards can be selected based on communication protocol or response data from the power-on operation, most of the cards require a selection through Application Identifier (AID) using the ISO7816-4 “Select Application” APDU command.

The structure outlined below allows for defining selection scenarios that combine these three types of filters:

• based on the communication protocol,
• based on the response data from the power on stage,
• based on the Application Identifier (AID).

When filtering by AID, the “Select Application” APDU command is sent to the card in accordance with the ISO7816-4 standard. Additional parameters, also defined by the standard, can be set to specify the type of operation (FileOccurrence) and the type of output (FileControlInformation).

Each filter is optional, and if none are defined, the selection is considered successful as soon as the card is detected. However, when a filter is specified, it becomes a prerequisite for the card selection.

In addition to card selection, a selection scenario can include a list of APDUs that are to be transmitted to the card as soon as it becomes “selected”.

The algorithm to be implemented by the terminal to process this service consists in iterating on the selection cases of the scenario.

For each selection case, the terminal must determine which type of filter to apply and apply it: protocol, power-on data, AID.

If all the defined filters are satisfied, the terminal must send any additional APDUs.

The terminal must then send the response to the server in a message of type “Card Selection (Response)”.

MessageDto

TransmitCardSelectionRequestsCmdBody

TransmitCardSelectionRequestsParameters

CardSelector

CardSelectionRequest

CardRequest

ApduRequest

Example

[
   {
      "apiLevel":2,
      "sessionId":"5bf1ca9a-2de9-4f16-b170-5de168560179",
      "action":"CMD",
      "clientNodeId":"824f32f1-ccb0-447c-a103-618152eb49ba",
      "serverNodeId":"fbf011a4-d0e2-4f3f-85c3-2ccd5be01919",
      "localReaderName":"stubReader",
      "remoteReaderName":"852f5841-0b5c-4922-a77a-b103cb5aac3f",
      "body":"{\"coreApiLevel\":2,\"service\":\"TRANSMIT_CARD_SELECTION_REQUESTS\",\"parameters\":{\"multiSelectionProcessing\":\"FIRST_MATCH\",\"channelControl\":\"KEEP_OPEN\",\"cardSelectors\":[{\"fileOccurrence\":\"FIRST\",\"fileControlInformation\":\"FCI\"}],\"cardSelectionRequests\":[{\"successfulSelectionStatusWords\":[\"9000\"]}]}}"
   }
]

Card Commands

The role of this service is to perform APDU exchanges with the card.

The terminal must iterate over the list of APDUs present in the card request and proceeds to close the physical channel if requested.

The response must be sent to the server in a message of type “Card Commands (Response)”.

MessageDto

TransmitCardRequestCmdBody

TransmitCardRequestParameters

CardRequest

ApduRequest

Example

[
    {
        "apiLevel": 2,
        "sessionId": "b1b8ed38-bae6-4b2e-a747-67d233652ea9",
        "action": "CMD",
        "clientNodeId": "ca21fd3c-a055-4be5-aad1-c61af3528371",
        "serverNodeId": "4132f1ef-4386-49b0-acb6-cc16035c107a",
        "localReaderName": "READER_1",
        "remoteReaderName": "a65f4920-7e96-4082-986a-b58d85978c07",
        "body": "{\"coreApiLevel\":2,\"service\":\"TRANSMIT_CARD_REQUEST\",\"parameters\":{\"cardRequest\":{\"apduRequests\":[{\"apdu\":\"00B2014400\",\"successfulStatusWords\":[\"9000\"],\"info\":\"Read Records - SFI: 8h, REC: 1, READMODE: ONE_RECORD, EXPECTEDLENGTH: 0\"}],\"stopOnUnsuccessfulStatusWord\":true},\"channelControl\":\"CLOSE_AFTER\"}}"
    }
]

Response

This message, sent by the terminal to the server, is intended to transmit to the server the result of the specific service previously performed on the card or the terminal’s reader.

Following the transmission of this message, the server will return a message of type “Command”, containing the next action to be performed, or of type “End Remote Service” to terminate the transaction.

The following UML class diagram illustrates the structure of this object and may help to implement it in the development language of the target terminal.

Card Presence

This message, sent by the terminal to the server in response to “Card Presence (Command)”, is intended to indicate to the server if a card is present.

MessageDto

IsCardPresentRespBody

Error

Example

{
    "apiLevel": 2,
    "sessionId": "b1b8ed38-bae6-4b2e-a747-67d233652ea9",
    "action": "RESP",
    "clientNodeId": "ca21fd3c-a055-4be5-aad1-c61af3528371",
    "serverNodeId": "4132f1ef-4386-49b0-acb6-cc16035c107a",
    "localReaderName": "READER_1",
    "remoteReaderName": "a65f4920-7e96-4082-986a-b58d85978c07",
    "body": "{\"coreApiLevel\":2,\"service\":\"IS_CARD_PRESENT\",\"result\":true}"
}

Card Selection

This message, sent by the terminal to the server in response to “Card Selection (Command)”, is intended to transmit to the server the result of the execution of the selection scenario.

MessageDto

TransmitCardSelectionRequestsRespBody

CardSelectionResponse

CardResponse

ApduResponse

Error

Example

{
    "apiLevel": 2,
    "sessionId": "b1b8ed38-bae6-4b2e-a747-67d233652ea9",
    "action": "RESP",
    "clientNodeId": "ca21fd3c-a055-4be5-aad1-c61af3528371",
    "serverNodeId": "4132f1ef-4386-49b0-acb6-cc16035c107a",
    "localReaderName": "READER_1",
    "remoteReaderName": "a65f4920-7e96-4082-986a-b58d85978c07",
    "body": "{\"coreApiLevel\":2,\"service\":\"TRANSMIT_CARD_SELECTION_REQUESTS\",\"result\":[{\"hasMatched\":true,\"powerOnData\":\"3B8880010000000000718100F9\",\"selectApplicationResponse\":{\"apdu\":\"6F238409315449432E49434131A516BF0C13C708000000001122334453070A3C23121410019000\",\"statusWord\":\"9000\"},\"cardResponse\":{\"apduResponses\":[{\"apdu\":\"24B92848080000131A50001200000000000000000000000000000000009000\",\"statusWord\":\"9000\"}],\"isLogicalChannelOpen\":true}}]}"
}

Card Commands

This message, sent by the terminal to the server in response to “Card Commands (Command)”, is intended to transmit to the server the result of the execution of a card request.

MessageDto

TransmitCardRequestRespBody

CardResponse

ApduResponse

Error

Example

{
    "apiLevel": 2,
    "sessionId": "b1b8ed38-bae6-4b2e-a747-67d233652ea9",
    "action": "RESP",
    "clientNodeId": "ca21fd3c-a055-4be5-aad1-c61af3528371",
    "serverNodeId": "4132f1ef-4386-49b0-acb6-cc16035c107a",
    "localReaderName": "READER_1",
    "remoteReaderName": "a65f4920-7e96-4082-986a-b58d85978c07",
    "body": "{\"coreApiLevel\":2,\"service\":\"TRANSMIT_CARD_REQUEST\",\"result\":{\"apduResponses\":[{\"apdu\":\"00112233445566778899AABBCCDDEEFF00112233445566778899AABBCC9000\",\"statusWord\":\"9000\"}],\"isLogicalChannelOpen\":true}}"
}

End Remote Service

The purpose of this message, received from the server, is to inform the terminal that the transaction has been completed and, if necessary, to transmit the result. No follow-up is expected from the server.

The following UML class diagram illustrates the structure of this object and may help to implement it in the development language of the target terminal.

MessageDto

EndRemoteServiceBody

Example

[
    {
        "apiLevel": 2,
        "sessionId": "b1b8ed38-bae6-4b2e-a747-67d233652ea9",
        "action": "END_REMOTE_SERVICE",
        "clientNodeId": "ca21fd3c-a055-4be5-aad1-c61af3528371",
        "serverNodeId": "4132f1ef-4386-49b0-acb6-cc16035c107a",
        "remoteReaderName": "a65f4920-7e96-4082-986a-b58d85978c07",
        "body": "{\"coreApiLevel\":2,\"outputData\":{\"isSuccessful\":true,\"userId\":\"test\"}}"
    }
]