Server JSON API 1.0

This API is compliant with the following Keyple server side components:


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:

MessageDto
MessageDto
The value of the action property determines the 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.

"Execute Remote Service" class diagram
“Execute Remote Service” class diagram

MessageDto

action String
Constant value: “EXECUTE_REMOTE_SERVICE
body String
A JSON string containing a ExecuteRemoteServiceBody JSON object.
sessionId String
The session identifier. It shall be unique per card transaction.
clientNodeId String
The terminal identifier. It shall be unique per server.
localReaderName String
The identifier of the local reader used to perform the card transaction. It shall be unique per terminal.
serverNodeId String (n/a)
Null or absent.
remoteReaderName String (n/a)
Null or absent.

ExecuteRemoteServiceBody

serviceId String
The identifier of the business service to be executed by the server. It’s a naming convention between the client and the server.
inputData Object (optional)
An optional object containing additional data to be provided to the remote business service. Its content is a convention between the client and the server.

Example

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

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 four types of service potentially requested by the server:

Service Description
Reader Type Indicates if the reader is in contact or contactless mode.
Card Presence Indicates if a card is present in the reader.
Card Selection Establish a logical communication channel with a card and, if required, perform additional APDU exchanges with it.
Card Commands Perform APDU exchanges with the selected card.

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.

"Command" class diagram
“Command” class diagram
The value of the service property determines the service to be performed.
The MessageDto is contained in a single-element array!

Reader Type

This service allows the server to know if the reader is in contact or contactless mode.

There are no parameters for this service.

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

The MessageDto is contained in a single-element array!

MessageDto

action String
Constant value: “CMD
body String
A JSON string containing a IsContactlessCmdBody JSON object.
sessionId String
The current transaction identifier as provided by the initial “Execute Remote Service” message.
clientNodeId String
The terminal identifier as provided by the initial “Execute Remote Service” message.
localReaderName String
The identifier of the local reader as provided by the initial “Execute Remote Service” message.
serverNodeId String
The server identifier.
remoteReaderName String
The identifier of the virtual remote reader linked to the local reader.
IsContactlessCmdBody
service String
Constant value: “IS_CONTACTLESS
Example
[
    {
        "action": "CMD",
        "body": "{\"service\":\"IS_CONTACTLESS\"}",
        "clientNodeId": "ca21fd3c-a055-4be5-aad1-c61af3528371",
        "localReaderName": "READER_1",
        "remoteReaderName": "a65f4920-7e96-4082-986a-b58d85978c07",
        "serverNodeId": "4132f1ef-4386-49b0-acb6-cc16035c107a",
        "sessionId": "b1b8ed38-bae6-4b2e-a747-67d233652ea9"
    }
]

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)”.

The MessageDto is contained in a single-element array!

MessageDto

action String
Constant value: “CMD
body String
A JSON string containing a IsCardPresentCmdBody JSON object.
sessionId String
The current transaction identifier as provided by the initial “Execute Remote Service” message.
clientNodeId String
The terminal identifier as provided by the initial “Execute Remote Service” message.
localReaderName String
The identifier of the local reader as provided by the initial “Execute Remote Service” message.
serverNodeId String
The server identifier.
remoteReaderName String
The identifier of the virtual remote reader linked to the local reader.
IsCardPresentCmdBody
service String
Constant value: “IS_CARD_PRESENT
Example
[
    {
        "action": "CMD",
        "body": "{\"service\":\"IS_CARD_PRESENT\"}",
        "clientNodeId": "ca21fd3c-a055-4be5-aad1-c61af3528371",
        "localReaderName": "READER_1",
        "remoteReaderName": "a65f4920-7e96-4082-986a-b58d85978c07",
        "serverNodeId": "4132f1ef-4386-49b0-acb6-cc16035c107a",
        "sessionId": "b1b8ed38-bae6-4b2e-a747-67d233652ea9"
    }
]

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)”.

The MessageDto is contained in a single-element array!

MessageDto

action String
Constant value: “CMD
body String
A JSON string containing a TransmitCardSelectionRequestsCmdBody JSON object.
sessionId String
The current transaction identifier as provided by the initial “Execute Remote Service” message.
clientNodeId String
The terminal identifier as provided by the initial “Execute Remote Service” message.
localReaderName String
The identifier of the local reader as provided by the initial “Execute Remote Service” message.
serverNodeId String
The server identifier.
remoteReaderName String
The identifier of the virtual remote reader linked to the local reader.
TransmitCardSelectionRequestsCmdBody
service String
Constant value: “TRANSMIT_CARD_SELECTION_REQUESTS
parameters TransmitCardSelectionRequestsParameters
The card selection parameters.
TransmitCardSelectionRequestsParameters
cardSelectionRequests CardSelectionRequest [ ]
A non-empty array.
multiSelectionProcessing String
Can have one of the following values:
- “FIRST_MATCH": the selection process stops as soon as a selection case is successful.
- “PROCESS_ALL": the selection process performs all the selection cases provided (the logical channel is closed at the end of the selection case).
channelControl String
Can have one of the following values:
- “KEEP_OPEN": leaves the physical channel open.
- “CLOSE_AFTER": terminates communication with the card.
CardSelectionRequest
cardSelector CardSelector
The card selection criteria.
cardRequest CardRequest (optional)
An optional object containing a list of APDU requests to be sent after a successful card selection.
CardSelector
cardProtocol String (optional)
An optional name of the targeted card protocol.
powerOnDataRegex String (optional)
An optional regex to use to filter the power-on data.
aid String (optional)
An optional Application Identifier (AID) as an hexadecimal string to be sent with ISO7816-4 “Select Application”.
fileOccurrence String
Can have one of the following values:
"FIRST”, “LAST”, “NEXT” or “PREVIOUS” according to the ISO7816-4 standard (only relevant when AID is set).
fileControlInformation String
Can have one of the following values:
"FCI”, “FCP”, “FMD” or “NO_RESPONSE” according to the ISO7816-4 standard (only relevant when AID is set).
successfulSelectionStatusWords String [ ]
A non-empty array of 2-byte hexadecimal strings containing the status word of the “Select Application” APDU command to be considered successful (only relevant when AID is set).
CardRequest
apduRequests ApduRequest [ ]
A non-empty array of APDU requests.
isStatusCodesVerificationEnabled Boolean
Set to true if the transmission of the APDUs should be interrupted as soon as the status word of a response does not belong to the associated list of successful status words, false otherwise.
ApduRequest
apdu String
An hexadecimal string containing the APDU to transmit to the card.
successfulStatusWords String [ ]
A non-empty array of 2-byte hexadecimal strings containing the status word to be considered successful.
info String (optional)
An optional textual information about the command.
Example
[
    {
        "action": "CMD",
        "body": "{\"service\":\"TRANSMIT_CARD_SELECTION_REQUESTS\",\"parameters\":{\"multiSelectionProcessing\":\"FIRST_MATCH\",\"channelControl\":\"KEEP_OPEN\",\"cardSelectionRequests\":[{\"cardSelector\":{\"cardProtocol\":\"ISO_14443_4_CARD\",\"aid\":\"315449432E49434131\",\"fileOccurrence\":\"FIRST\",\"fileControlInformation\":\"FCI\",\"successfulSelectionStatusWords\":[\"9000\"]},\"cardRequest\":{\"apduRequests\":[{\"apdu\":\"00B2013C00\",\"successfulStatusWords\":[\"9000\"],\"info\":\"Read Records - SFI: 7h, REC: 1, READMODE: ONE_RECORD, EXPECTEDLENGTH: 0\"}],\"isStatusCodesVerificationEnabled\":false}}]}}",
        "clientNodeId": "ca21fd3c-a055-4be5-aad1-c61af3528371",
        "localReaderName": "READER_1",
        "remoteReaderName": "a65f4920-7e96-4082-986a-b58d85978c07",
        "serverNodeId": "4132f1ef-4386-49b0-acb6-cc16035c107a",
        "sessionId": "b1b8ed38-bae6-4b2e-a747-67d233652ea9"
    }
]

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)”.

The MessageDto is contained in a single-element array!

MessageDto

action String
Constant value: “CMD
body String
A JSON string containing a TransmitCardRequestCmdBody JSON object.
sessionId String
The current transaction identifier as provided by the initial “Execute Remote Service” message.
clientNodeId String
The terminal identifier as provided by the initial “Execute Remote Service” message.
localReaderName String
The identifier of the local reader as provided by the initial “Execute Remote Service” message.
serverNodeId String
The server identifier.
remoteReaderName String
The identifier of the virtual remote reader linked to the local reader.
TransmitCardRequestCmdBody
service String
Constant value: “TRANSMIT_CARD_REQUEST
parameters TransmitCardRequestParameters
The card request parameters.
TransmitCardRequestParameters
cardRequest CardRequest
An object containing the list of APDU requests to be sent.
channelControl String
Can have one of the following values:
- “KEEP_OPEN": leaves the physical channel open.
- “CLOSE_AFTER": terminates communication with the card.
CardRequest
apduRequests ApduRequest [ ]
A non-empty array of APDU requests.
isStatusCodesVerificationEnabled Boolean
Set to true if the transmission of the APDUs should be interrupted as soon as the status word of a response does not belong to the associated list of successful status words, false otherwise.
ApduRequest
apdu String
An hexadecimal string containing the APDU to transmit to the card.
successfulStatusWords String [ ]
A non-empty array of 2-byte hexadecimal strings containing the status word to be considered successful.
info String (optional)
An optional textual information about the command.
Example
[
    {
        "action": "CMD",
        "body": "{\"service\":\"TRANSMIT_CARD_REQUEST\",\"parameters\":{\"cardRequest\":{\"apduRequests\":[{\"apdu\":\"00B2014400\",\"successfulStatusWords\":[\"9000\"],\"info\":\"Read Records - SFI: 8h, REC: 1, READMODE: ONE_RECORD, EXPECTEDLENGTH: 0\"}],\"isStatusCodesVerificationEnabled\":true},\"channelControl\":\"CLOSE_AFTER\"}}",
        "clientNodeId": "ca21fd3c-a055-4be5-aad1-c61af3528371",
        "localReaderName": "READER_1",
        "remoteReaderName": "a65f4920-7e96-4082-986a-b58d85978c07",
        "serverNodeId": "4132f1ef-4386-49b0-acb6-cc16035c107a",
        "sessionId": "b1b8ed38-bae6-4b2e-a747-67d233652ea9"
    }
]

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.

"Response" class diagram
“Response” class diagram

Reader Type

This message, sent by the terminal to the server in response to “Reader Type (Command)”, is intended to indicate to the server if the reader is contactless.

MessageDto

action String
Constant value: “RESP
body String
A JSON string containing a IsContactlessRespBody JSON object.
sessionId String
The current transaction identifier as provided by the initial “Execute Remote Service” message.
clientNodeId String
The terminal identifier as provided by the initial “Execute Remote Service” message.
localReaderName String
The identifier of the local reader as provided by the initial “Execute Remote Service” message.
serverNodeId String
The server identifier as provided by the last “Command” message.
remoteReaderName String
The identifier of the virtual remote reader linked to the local reader as provided by the last “Command” message.
IsContactlessRespBody
service String
Constant value: “IS_CONTACTLESS
result Boolean (optional)
Set to true if the reader is contactless, false otherwise (absent in case of error).
error Error (optional)
The error description (absent in case of success).
Error
code String
Free value.
message String
The error description.

Example

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

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

action String
The value is “RESP”.
body String
A JSON string containing a IsCardPresentRespBody JSON object.
sessionId String
The current transaction identifier as provided by the initial “Execute Remote Service” message.
clientNodeId String
The terminal identifier as provided by the initial “Execute Remote Service” message.
localReaderName String
The identifier of the local reader as provided by the initial “Execute Remote Service” message.
serverNodeId String
The server identifier as provided by the last “Command” message.
remoteReaderName String
The identifier of the virtual remote reader linked to the local reader as provided by the last “Command” message.
IsCardPresentRespBody
service String
Constant value: “IS_CARD_PRESENT
result Boolean
Set to true if a card is present, false otherwise (absent in case of error).
error Error (optional)
The error description (absent in case of success).
Error
code String
Can have one of the following values:
- “READER_COMMUNICATION_ERROR": if the issue is related to the reader communication link,
- “CARD_COMMUNICATION_ERROR": if the issue is related to the card communication link.
message String
The error description.

Example

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

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

action String
Constant value: “RESP
body String
A JSON string containing a TransmitCardSelectionRequestsRespBody JSON object.
sessionId String
The current transaction identifier as provided by the initial “Execute Remote Service” message.
clientNodeId String
The terminal identifier as provided by the initial “Execute Remote Service” message.
localReaderName String
The identifier of the local reader as provided by the initial “Execute Remote Service” message.
serverNodeId String
The server identifier as provided by the last “Command” message.
remoteReaderName String
The identifier of the virtual remote reader linked to the local reader as provided by the last “Command” message.
TransmitCardSelectionRequestsRespBody
service String
Constant value: “TRANSMIT_CARD_SELECTION_REQUESTS
result CardSelectionResponse [ ] (optional)
A non-empty list containing at most as many responses as there are selection cases (absent in case of error).
error Error (optional)
The error description (absent in case of success).
CardSelectionResponse
hasMatched Boolean
Set to true if the associated selection case has matched, false otherwise.
powerOnData String (optional)
Data from the initialization phase of the communication with the card. E.g. the Answer To Reset (ATR) in the case of a contact card or any other string informing about the low level communication. This string can be used for filtering by power-on data defined in the command (absent if the protocol filter failed).
selectApplicationResponse ApduResponse (optional)
Data received in response to the ISO7816-4 “Select Application” command (absent if no AID filtering).
cardResponse CardResponse (optional)
Data received in response to additional commands (absent if no additional commands were provided).
CardResponse
isLogicalChannelOpen Boolean
Set to true if the logical channel is left open, false otherwise.
apduResponses ApduResponse [ ]
A list containing the APDU responses for each request in the command.
ApduResponse
apdu String
An hexadecimal string containing the APDU received from the card (including the status word).
statusWord String
A 2-byte hexadecimal string containing the status word of the received APDU.
Error
code String
Can have one of the following values:
- “READER_COMMUNICATION_ERROR": if the issue is related to the reader communication link,
- “CARD_COMMUNICATION_ERROR": if the issue is related to the card communication link,
- “CARD_COMMAND_ERROR": if the card returned an unexpected status word.
message String
The error description.
Example
{
    "action": "RESP",
    "body": "{\"service\":\"TRANSMIT_CARD_SELECTION_REQUESTS\",\"result\":[{\"hasMatched\":true,\"powerOnData\":\"3B8880010000000000718100F9\",\"selectApplicationResponse\":{\"apdu\":\"6F238409315449432E49434131A516BF0C13C708000000001122334453070A3C23121410019000\",\"statusWord\":\"9000\"},\"cardResponse\":{\"apduResponses\":[{\"apdu\":\"24B92848080000131A50001200000000000000000000000000000000009000\",\"statusWord\":\"9000\"}],\"isLogicalChannelOpen\":true}}]}",
    "clientNodeId": "ca21fd3c-a055-4be5-aad1-c61af3528371",
    "localReaderName": "READER_1",
    "remoteReaderName": "a65f4920-7e96-4082-986a-b58d85978c07",
    "serverNodeId": "4132f1ef-4386-49b0-acb6-cc16035c107a",
    "sessionId": "b1b8ed38-bae6-4b2e-a747-67d233652ea9"
}

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

action String
Constant value: “RESP
body String
A JSON string containing a TransmitCardRequestRespBody JSON object.
sessionId String
The current transaction identifier as provided by the initial “Execute Remote Service” message.
clientNodeId String
The terminal identifier as provided by the initial “Execute Remote Service” message.
localReaderName String
The identifier of the local reader as provided by the initial “Execute Remote Service” message.
serverNodeId String
The server identifier as provided by the last “Command” message.
remoteReaderName String
The identifier of the virtual remote reader linked to the local reader as provided by the last “Command” message.
TransmitCardRequestRespBody
service String
Constant value: “TRANSMIT_CARD_REQUEST
result CardResponse (optional)
Data received in response to the card request (absent in case of error).
error Error (optional)
The error description (absent in case of success).
CardResponse
isLogicalChannelOpen Boolean
Set to true if the logical channel is left open, false otherwise.
apduResponses ApduResponse [ ]
A list containing the APDU responses for each request in the command.
ApduResponse
apdu String
An hexadecimal string containing the APDU received from the card (including the status word).
statusWord String
A 2-byte hexadecimal string containing the status word of the received APDU.
Error
code String
Can have one of the following values:
- “READER_COMMUNICATION_ERROR": if the issue is related to the reader communication link,
- “CARD_COMMUNICATION_ERROR": if the issue is related to the card communication link,
- “CARD_COMMAND_ERROR": if the card returned an unexpected status word.
message String
The error description.
Example
{
    "action": "RESP",
    "body": "{\"service\":\"TRANSMIT_CARD_REQUEST\",\"result\":{\"apduResponses\":[{\"apdu\":\"00112233445566778899AABBCCDDEEFF00112233445566778899AABBCC9000\",\"statusWord\":\"9000\"}],\"isLogicalChannelOpen\":true}}",
    "clientNodeId": "ca21fd3c-a055-4be5-aad1-c61af3528371",
    "localReaderName": "READER_1",
    "remoteReaderName": "a65f4920-7e96-4082-986a-b58d85978c07",
    "serverNodeId": "4132f1ef-4386-49b0-acb6-cc16035c107a",
    "sessionId": "b1b8ed38-bae6-4b2e-a747-67d233652ea9"
}

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.

"End Remote Service" class diagram
“End Remote Service” class diagram
The MessageDto is contained in a single-element array!

MessageDto

action String
Constant value: “END_REMOTE_SERVICE
body String
A JSON string containing a EndRemoteServiceBody JSON object.
sessionId String
The current transaction identifier as provided by the initial “Execute Remote Service” message.
clientNodeId String
The terminal identifier as provided by the initial “Execute Remote Service” message.
localReaderName String (n/a)
Null or absent.
serverNodeId String
The server identifier.
remoteReaderName String
The identifier of the virtual remote reader linked to the local reader.

EndRemoteServiceBody

outputData Object (optional)
An optional object containing additional data provided by the remote business service. Its content is a convention between the client and the server.

Example

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