Server JSON API 1.0

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

{
    "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:

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.

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

MessageDto

IsContactlessCmdBody

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

MessageDto

IsCardPresentCmdBody

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

MessageDto

TransmitCardSelectionRequestsCmdBody

TransmitCardSelectionRequestsParameters

CardSelectionRequest

CardSelector

CardRequest

ApduRequest

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

MessageDto

TransmitCardRequestCmdBody

TransmitCardRequestParameters

CardRequest

ApduRequest

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.

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

IsContactlessRespBody

Error

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

IsCardPresentRespBody

Error

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

TransmitCardSelectionRequestsRespBody

CardSelectionResponse

CardResponse

ApduResponse

Error

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

TransmitCardRequestRespBody

CardResponse

ApduResponse

Error

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.

MessageDto

EndRemoteServiceBody

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"
    }
]