swagger: '2.0'
info:
  description: Gemalto TSH Device Gateway API - TSH to TES
  termsOfService: Copyright (c) 2018 GEMALTO. All Rights Reserved
  title: Gemalto TSH Device Gateway API - TSH to TES
  version: 1.0.20
schemes:
  - http
  - https
basePath: /tes/devicegtwapi/1/0
consumes:
  - application/json
produces:
  - application/json
parameters:
  actorHeader:
    description: HTTP header identifying the actor initiating the request.
    in: header
    name: x-actor-id
    type: string
    required: true
    maxLength: 32
paths:
  /getCardCommands:
    post:
      summary: Request to provide the next list of commands to be executed on a device
      description: This method is used by TSH to request the pending commands to be executed on a device.</br> It is used for reading/updating the content of a device (e.g. topup).</br> The TES has to return the list of commands that needs to be executed on the device after checking the previous commands responses.</br>
      operationId: getCardCommands
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/actorHeader'
        - name: body
          in: body
          description: getCardCommands request payload
          required: true
          schema:
            $ref: '#/definitions/getCardCommandsReq'
      responses:
        '200':
          description: getCardCommands response payload
          schema:
            $ref: '#/definitions/getCardCommandsRes'
        '500':
          description: Internal Server Error
  /getParkCardCommands:
    post:
      summary: Request to provide the next list of commands to be executed on a device for parking a card
      description: 'This method is used by TSH to request the pending commands to be executed on a device.</br> It is used for parking a card (meaning reading the current balance of a card for storing it on server side).</br> The TES has to return the list of commands that needs to be executed on the device after checking the previous commands responses.</br> Once the card has been parked on TES side, the TES has to return the card balance to TSH on last response.'
      operationId: getParkCardCommands
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/actorHeader'
        - name: body
          in: body
          description: getParkCardCommands request payload
          required: true
          schema:
            $ref: '#/definitions/getParkCardCommandsReq'
      responses:
        '200':
          description: getParkCardCommands response payload
          schema:
            $ref: '#/definitions/getParkCardCommandsRes'
        '500':
          description: Internal Server Error
  /getReaderModeCommands:
    post:
      summary: Request to provide the next list of reader mode commands to be executed on a device
      description: 'This method is used by TSH to request the pending reader mode commands to be executed on a device.</br> It is used for reading/updating the content of an external device.</br> The TES has to return the list of commands that needs to be executed on the device after checking the previous commands responses.</br> Once the card has been ingested on TES side, the TES has to create a new card account and return the card balance and card account identifier to TSH on last response.'
      operationId: getReaderModeCommands
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/actorHeader'
        - name: body
          in: body
          description: getReaderModeCommands request payload
          required: true
          schema:
            $ref: '#/definitions/getReaderModeCommandsReq'
      responses:
        '200':
          description: getReaderModeCommands response payload
          schema:
            $ref: '#/definitions/getReaderModeCommandsRes'
        '500':
          description: Internal Server Error
definitions:
  getCardCommandsReq:
    type: object
    required:
      - requestHeader
      - issuerId
      - cardId
      - deviceId
    properties:
      requestHeader:
        $ref: '#/definitions/requestHeader'
      issuerId:
        $ref: '#/definitions/issuerId'
      cardId:
        $ref: '#/definitions/cardId'
      purchaseId:
        maxLength: 64
        minLength: 1
        type: string
        description: The Purchase Identifier. Unique for each purchase.<br/> It is provided when the call is related to topup initiated from wallet.
      deviceId:
        $ref: '#/definitions/deviceId'
      operation:
        $ref: '#/definitions/operation'
      responses:
        $ref: '#/definitions/responses'
      responseTimeMs:
        $ref: '#/definitions/responseTimeMs'
      statusCode:
        $ref: '#/definitions/statusCode'
      statusMessage:
        $ref: '#/definitions/statusMessage'
  getCardCommandsRes:
    type: object
    required:
      - responseHeader
    properties:
      responseHeader:
        $ref: '#/definitions/responseHeader'
      commands:
        $ref: '#/definitions/commands'
  getReaderModeCommandsReq:
    type: object
    required:
      - requestHeader
      - issuerId
      - deviceId
    properties:
      requestHeader:
        $ref: '#/definitions/requestHeader'
      issuerId:
        $ref: '#/definitions/issuerId'
      deviceId:
        $ref: '#/definitions/deviceId'
      operation:
        $ref: '#/definitions/operation'
      responses:
        $ref: '#/definitions/responses'
      responseTimeMs:
        $ref: '#/definitions/responseTimeMs'
      cardContents:
        $ref: '#/definitions/cardContents'
      statusCode:
        $ref: '#/definitions/statusCode'
      statusMessage:
        $ref: '#/definitions/statusMessage'
  getReaderModeCommandsRes:
    type: object
    required:
      - responseHeader
    properties:
      responseHeader:
        $ref: '#/definitions/responseHeader'
      commands:
        $ref: '#/definitions/commands'
      cardAccountId:
        $ref: '#/definitions/cardAccountId'
      cardData:
        $ref: '#/definitions/cardData'
  getParkCardCommandsReq:
    type: object
    required:
      - requestHeader
      - issuerId
      - cardId
      - deviceId
    properties:
      requestHeader:
        $ref: '#/definitions/requestHeader'
      issuerId:
        $ref: '#/definitions/issuerId'
      cardId:
        $ref: '#/definitions/cardId'
      deviceId:
        $ref: '#/definitions/deviceId'
      operation:
        $ref: '#/definitions/operation'
      responses:
        $ref: '#/definitions/responses'
      responseTimeMs:
        $ref: '#/definitions/responseTimeMs'
      statusCode:
        $ref: '#/definitions/statusCode'
      statusMessage:
        $ref: '#/definitions/statusMessage'
  getParkCardCommandsRes:
    type: object
    required:
      - responseHeader
    properties:
      responseHeader:
        $ref: '#/definitions/responseHeader'
      commands:
        $ref: '#/definitions/commands'
      cardData:
        $ref: '#/definitions/cardData'
  cardId:
    maxLength: 48
    minLength: 1
    type: string
    description: The Card Identifier. Unique for each card.
  cardAccountId:
    maxLength: 48
    minLength: 1
    type: string
    description: The Card Account Identifier. Unique for each card account.
  cardData:
    type: object
    properties:
      balanceAmount:
        $ref: '#/definitions/balanceAmount'
  balanceAmount:
    type: number
    format: double
    description: The current balance amount of the card
  issuerId:
    maxLength: 16
    minLength: 1
    type: string
    description: The Card Issuer Identifier. Unique for each card issuer.
  deviceId:
    maxLength: 48
    minLength: 1
    type: string
    description: The Device Identifier. Unique for each device.
  operation:
    type: string
    description: The operation for which the commands are requested
    enum:
      - READ_BALANCE
      - UPDATE_BALANCE
      - UPDATE_CONFIG
      - UPDATE_PLAN
      - ERASE_CARD
      - PARK_CARD
      - BLOCK_AND_READ_CARD
  cardContents:
    type: object
    description: "This object gives a description of the external SE.</br> For FeliCa, the following can be provided:\n```\n\"cardContents\": {\n\t\"cardServiceId\" : \"Test Service\",\n\t\"systemCode\" : \"FE00\",\n\t\"idm\" : \"1122334455667788\",\n\t\"pmm\" : \"0000000000000000\",\n\t\"areaCodeList\" : [\n\t\t{\n\t\t\t\"areaCode\" : \"0100\",\n\t\t\t\"keyVersion\" : \"6745\"\n\t\t},\n\t\t{\n\t\t\t\"areaCode\" : \"1000\",\n\t\t\t\"keyVersion\" : \"4567\"\n\t\t}\n\t]\n}\n```"
  commands:
    type: array
    maxItems: 200
    description: List of commands to be executed on the device.
    items:
      type: object
      properties:
        id:
          type: string
          description: ID of the command
          maxLength: 64
          minLength: 1
        name:
          type: string
          description: Descriptive name of the command
          maxLength: 100
          minLength: 1
        value:
          type: string
          description: Hex encoded string command value
          maxLength: 512
          minLength: 1
  responseTimeMs:
    type: number
    format: double
    description: Total time of all executed commands listed in responses array in milliseconds.
  responses:
    type: array
    maxItems: 200
    description: List of the responses executed on the device.
    items:
      type: object
      properties:
        id:
          type: string
          description: ID of the command that has been executed.</br> Extracted from the original message.
          maxLength: 64
          minLength: 1
        name:
          type: string
          description: Descriptive name of the command that has been executed.</br> Extracted from the original message and appended with "_RESP"
          maxLength: 100
          minLength: 1
        value:
          type: string
          description: Hex encoded string command response
          maxLength: 512
          minLength: 1
  requestId:
    description: Unique request identifier
    maxLength: 48
    minLength: 1
    type: string
  responseId:
    description: Unique response identifier
    maxLength: 48
    minLength: 1
    type: string
  sessionId:
    description: Unique session identifier used to trace the calls across systems during a use case.
    maxLength: 48
    minLength: 1
    type: string
  generationDateTime:
    description: 'Date time representing when the request or response has been generated.<br/>RFC3339 format.<br/> Examples:<li>"2018-12-24T17:32:28Z"<li>"2019-10-02T10:00:00-05:00"'
    type: string
    format: date-time
  requestHeader:
    type: object
    required:
      - requestId
      - sessionId
    properties:
      requestId:
        $ref: '#/definitions/requestId'
      sessionId:
        $ref: '#/definitions/sessionId'
      generationDateTime:
        $ref: '#/definitions/generationDateTime'
  statusCode:
    type: number
    description: |
      Status code to the request
      |Status code | Description|
      |-------|-------|
      |0|OK|
      |111|Missing mandatory parameter|
      |112|Bad parameter format|
      |113|Unknown issuer|
      |117|Unknown device|
      |118|Unknown session|
      |119|Unknown virtual card|
      |159|Card is blacklisted|
      |160|Card is deleted|
      |162|Card has unsufficient balance|
      |163|Card product not eligible|
      |167|Card is already provisioned|
      |172|Invalid card, unsupported system code|
      |173|Invalid card, unsupported service|
      |177|Invalid card, invalid area data|
      |178|Invalid card, card status is in-station|
      |191|Card is expired|
      |192|Reader mode attempt exceeded allowed threshold|
      |221|Device or wallet server not accessible|
      |231|Device unexpected error|
      |232|Device out of memory error|
      |321|Operation already on-going for this device|
      |322|Time to live of the operation expired|
      |323|Operation incomplete|      
      |911|Operation failed|
      |921|Unexpected server error|
  statusMessage:
    type: string
    description: Textual status message
  responseHeader:
    type: object
    required:
      - responseId
      - sessionId
      - statusCode
    properties:
      responseId:
        $ref: '#/definitions/responseId'
      sessionId:
        $ref: '#/definitions/sessionId'
      generationDateTime:
        $ref: '#/definitions/generationDateTime'
      statusCode:
        $ref: '#/definitions/statusCode'
      statusMessage:
        $ref: '#/definitions/statusMessage'
