swagger: '2.0'
info:
  description: Gemalto TSH Transit API - TES to TSH
  termsOfService: Copyright (c) 2018 GEMALTO. All Rights Reserved
  title: Gemalto TSH Transit API - TES to TSH
  version: 1.0.20
schemes:
  - http
  - https
basePath: /tsh/transitapi/1/0
consumes:
  - application/json
produces:
  - application/json
paths:
  /submitCardPersoData:
    post:
      summary: Request to send personalization data to a digital card
      description: This method is used by TES to submit the perso data used for personalizing a digital card.</br> This request is sent after TES approves a previous provisionCard call and after finishing to prepare the required data.</br>
      operationId: submitCardPersoData
      produces:
        - application/json
      parameters:
        - name: body
          in: body
          description: submitCardPersoData request payload
          required: true
          schema:
            $ref: '#/definitions/submitCardPersoDataReq'
      responses:
        '200':
          description: submitCardPersoData response payload
          schema:
            $ref: '#/definitions/submitCardPersoDataRes'
        '500':
          description: Internal Server Error
  /updateCardState:
    post:
      summary: Request to update the state of a digital card
      description: This method is used by TES to request to update the state of a digital card.
      operationId: updateCardState
      produces:
        - application/json
      parameters:
        - name: body
          in: body
          description: updateCardState request payload
          required: true
          schema:
            $ref: '#/definitions/updateCardStateReq'
      responses:
        '200':
          description: updateCardState response payload
          schema:
            $ref: '#/definitions/updateCardStateRes'
        '500':
          description: Internal Server Error
  /updateCardMetadata:
    post:
      summary: Request to update the metadata of a card
      description: "This method is used by TES to request to update the metadata of a digital card:<ul><li>either commute plans metadata<li>or card arts</ul>\r\nIt's not possible to update them both in a single request. "
      operationId: updateCardMetadata
      produces:
        - application/json
      parameters:
        - name: body
          in: body
          description: updateCardMetadata request payload
          required: true
          schema:
            $ref: '#/definitions/updateCardMetadataReq'
      responses:
        '200':
          description: updateCardMetadata response payload
          schema:
            $ref: '#/definitions/updateCardMetadataRes'
        '500':
          description: Internal Server Error
  /initiateCardSession:
    post:
      summary: Request to initiate a session for a digital card
      description: This method is used by TES to request TSH to initiate a session for a digital card.</br> This request is sent when TES needs to exchange commands with targeted device (during a topup for example).</br>
      operationId: initiateCardSession
      produces:
        - application/json
      parameters:
        - name: body
          in: body
          description: initiateCardSession request payload
          required: true
          schema:
            $ref: '#/definitions/initiateCardSessionReq'
      responses:
        '200':
          description: initiateCardSession response payload
          schema:
            $ref: '#/definitions/initiateCardSessionRes'
        '500':
          description: Internal Server Error
  /getCards:
    post:
      summary: Request to get the list of cards details associated to a card account
      description: This method is used by TES to request TSH to return the list of cards associated to the specified card account.
      operationId: getCards
      produces:
        - application/json
      parameters:
        - name: body
          in: body
          description: getCards request payload
          required: true
          schema:
            $ref: '#/definitions/getCardsReq'
      responses:
        '200':
          description: getCards response payload
          schema:
            $ref: '#/definitions/getCardsRes'
        '500':
          description: Internal Server Error
  /refundCardAccount:
    post:
      summary: Request to refund a card account
      description: This method is used by TES to notify TSH that a card account has been refunded.
      operationId: refundCardAccount
      produces:
        - application/json
      parameters:
        - name: body
          in: body
          description: refundCardAccount request payload
          required: true
          schema:
            $ref: '#/definitions/refundCardAccountReq'
      responses:
        '200':
          description: refundCardAccount response payload
          schema:
            $ref: '#/definitions/refundCardAccountRes'
        '500':
          description: Internal Server Error
  /getRequestStatus:
    post:
      summary: Get request status
      description: This method is used by TES to check the status of an asynchronous request previously submitted.
      operationId: getRequestStatus
      produces:
        - application/json
      parameters:
        - name: body
          in: body
          description: getRequestStatus request payload
          required: true
          schema:
            $ref: '#/definitions/getRequestStatusReq'
      responses:
        '200':
          description: getRequestStatus response payload
          schema:
            $ref: '#/definitions/getRequestStatusRes'
        '500':
          description: Internal Server Error
definitions:
  submitCardPersoDataReq:
    type: object
    required:
      - requestHeader
      - issuerId
      - cardId
      - cardPersoData
    properties:
      requestHeader:
        $ref: '#/definitions/requestHeader'
      issuerId:
        $ref: '#/definitions/issuerId'
      cardId:
        $ref: '#/definitions/cardId'
      cardPersoData:
        $ref: '#/definitions/cardPersoData'
  submitCardPersoDataRes:
    type: object
    required:
      - responseHeader
    properties:
      responseHeader:
        $ref: '#/definitions/responseHeader'
  updateCardStateReq:
    type: object
    required:
      - requestHeader
      - issuerId
      - cardId
      - action
    properties:
      requestHeader:
        $ref: '#/definitions/requestHeader'
      issuerId:
        $ref: '#/definitions/issuerId'
      cardId:
        $ref: '#/definitions/cardId'
      action:
        $ref: '#/definitions/action'
  updateCardStateRes:
    type: object
    required:
      - responseHeader
    properties:
      responseHeader:
        $ref: '#/definitions/responseHeader'
  updateCardMetadataReq:
    type: object
    properties:
      requestHeader:
        $ref: '#/definitions/requestHeader'
      issuerId:
        $ref: '#/definitions/issuerId'
      cardId:
        $ref: '#/definitions/cardId'
      commutePlans:
        $ref: '#/definitions/commutePlans'
      cardArtManifest:
        type: array
        description: |-
          Array of asset identifiers required to build
          card arts.
          Both cardBackground and icon asset identifiers shall be provided.

          Asset identifier can be up to 64 characters.

          When this parameter is provided, a request will be sent to wallet provider for updating the card arts deployed with the ones specified
        items:
          type: string
    required:
      - requestHeader
      - issuerId
      - cardId
  updateCardMetadataRes:
    type: object
    required:
      - responseHeader
    properties:
      responseHeader:
        $ref: '#/definitions/responseHeader'
  initiateCardSessionReq:
    type: object
    required:
      - requestHeader
      - issuerId
      - cardId
    properties:
      requestHeader:
        $ref: '#/definitions/requestHeader'
      issuerId:
        $ref: '#/definitions/issuerId'
      cardId:
        $ref: '#/definitions/cardId'
      operation:
        $ref: '#/definitions/operation'
  initiateCardSessionRes:
    type: object
    required:
      - responseHeader
    properties:
      responseHeader:
        $ref: '#/definitions/responseHeader'
  getCardsReq:
    type: object
    required:
      - requestHeader
      - issuerId
      - cardAccountId
    properties:
      requestHeader:
        $ref: '#/definitions/requestHeader'
      issuerId:
        $ref: '#/definitions/issuerId'
      cardAccountId:
        $ref: '#/definitions/cardAccountId'
  getCardsRes:
    type: object
    required:
      - responseHeader
    properties:
      responseHeader:
        $ref: '#/definitions/responseHeader'
      walletCardAccountId:
        $ref: '#/definitions/walletCardAccountId'
      walletAccountId:
        $ref: '#/definitions/walletAccountId'
      cardAccountState:
        type: string
        enum:
          - ACTIVE
          - CANCELLED
          - PARKED
      cards:
        $ref: '#/definitions/cards'
  refundCardAccountReq:
    type: object
    required:
      - requestHeader
      - issuerId
      - cardAccountId
    properties:
      requestHeader:
        $ref: '#/definitions/requestHeader'
      issuerId:
        $ref: '#/definitions/issuerId'
      cardAccountId:
        $ref: '#/definitions/cardAccountId'
  refundCardAccountRes:
    type: object
    required:
      - responseHeader
    properties:
      responseHeader:
        $ref: '#/definitions/responseHeader'
  getRequestStatusReq:
    type: object
    required:
      - requestHeader
      - issuerId
      - targetRequestId
    properties:
      requestHeader:
        $ref: '#/definitions/requestHeader'
      issuerId:
        $ref: '#/definitions/issuerId'
      targetRequestId:
        $ref: '#/definitions/requestId'
  getRequestStatusRes:
    type: object
    required:
      - responseHeader
    properties:
      responseHeader:
        $ref: '#/definitions/responseHeader'
      requestStatus:
        $ref: '#/definitions/requestStatus'
  commutePlans:
    type: array
    maxItems: 10
    items:
      type: object
      required:
        - identifier
        - title
        - usage
        - validityPeriod
      properties:
        identifier:
          description: 'Identifier of a plan, unique to the list of plans.'
          type: string
          minLength: 1
          maxLength: 128
        title:
          type: array
          maxItems: 10
          items:
            type: object
            required:
              - label
              - language
            properties:
              label:
                description: 'Commute plan title label.</br> Examples:<li>First Ferry Monthly Ticket<li>First Ferry Weekly Ticket'
                type: string
                minLength: 1
                maxLength: 64
              value:
                description: 'Commute plan title extra details.</br> Examples:<li>North Point<li>Hunghom - Kowloon City'
                type: string
                minLength: 1
                maxLength: 64
              language:
                type: string
                description: 'Text language as defined by BCP 47 standard.</br> Examples:<li>en-US<li>zh-CN'
                maxLength: 16
                minLength: 1
        usage:
          type: object
          required:
            - label
            - value
          properties:
            label:
              description: Label describing commute plan usage
              type: string
              enum:
                - Usage
                - Limitations
            value:
              type: array
              maxItems: 10
              items:
                type: object
                required:
                  - text
                  - language
                properties:
                  text:
                    type: string
                    description: Descriptive text about commute plan usage
                    maxLength: 128
                    minLength: 1
                  language:
                    type: string
                    description: 'Text language as defined by BCP 47 standard.</br> Examples:<li>en-US<li>zh-CN'
                    maxLength: 16
                    minLength: 1
        validityPeriod:
          type: object
          required:
            - startDate
            - expiryDate
          properties:
            startDate:
              description: 'Starting date of the commute plan (can be in the future).<br/>RFC3339 format<br/> Examples:<li>"2018-11-24T17:32:28Z"<li>"2019-10-02T10:00:00-05:00"'
              type: string
              format: date-time
            expiryDate:
              description: 'Ending date of the commute plan.<br/>RFC3339 format<br/> Examples:<li>"2018-12-24T17:32:28Z"<li>"2019-10-09T10:00:00-05:00"'
              type: string
              format: date-time
            dateStyle:
              type: string
              description: 'Style of the date to be displayed on user device. Default value is "MEDIUM".</br> Examples:<li>SHORT ==> "11/23/19"<li>MEDIUM ==> "Nov 23, 2019"<li>LONG ==> "November 23, 2019"'
              enum:
                - SHORT
                - MEDIUM
                - LONG
            timeStyle:
              type: string
              description: 'Style of the date to be displayed on user device. Default value is "SHORT".</br> Examples:<li>SHORT ==> "3:30 PM"<li>MEDIUM ==> "3:30:32 PM"<li>LONG ==> "3:30:32 PM PST"'
              enum:
                - SHORT
                - MEDIUM
                - LONG
  cardId:
    maxLength: 48
    minLength: 1
    type: string
    description: The Card Identifier. Unique for each card.
  requestStatus:
    type: string
    description: The status of the request.
    enum:
      - PROCESSING
      - COMPLETED
      - FAILED
  walletCardId:
    maxLength: 64
    minLength: 1
    type: string
    description: The Wallet Card Identifier. Unique for each wallet card.
  cardAccountId:
    maxLength: 48
    minLength: 1
    type: string
    description: The Card Account Identifier. Unique for each card account.
  walletCardAccountId:
    maxLength: 64
    minLength: 1
    type: string
    description: The Wallet Card Account Identifier. Unique for each wallet card account.
  walletAccountId:
    maxLength: 128
    minLength: 1
    type: string
    description: The Wallet Account Identifier. Unique for each wallet account.
  cards:
    type: array
    maxItems: 100
    description: List of cards
    items:
      type: object
      properties:
        cardId:
          $ref: '#/definitions/cardId'
        walletCardId:
          $ref: '#/definitions/walletCardId'
        cardState:
          type: string
          enum:
            - CREATED
            - ACTIVE
            - SUSPENDED_ISSUER
            - SUSPENDED_WALLET
            - UNLINKED
  cardPersoData:
    type: array
    maxItems: 200
    description: Perso Data to be used for personalizing a digital card.
    items:
      type: object
      required:
        - name
        - value
      properties:
        name:
          type: string
          description: 'Data element name (for example, the DGI code)'
          maxLength: 32
          minLength: 1
        value:
          type: string
          description: Data element value
          maxLength: 8192
          minLength: 1
        keyIndex:
          type: string
          description: Index of the key used to encrypt the value (if encrypted)
          minLength: 1
          maxLength: 32
  action:
    type: string
    description: |-
      The LCM action to apply on the card.</br>Possible values are:
        - DELETE
        - SUSPEND
        - RESUME
        - ERASE (used in the Rights of Individuals context)
          All personal data are physically removed from TSH server
    enum:
      - DELETE
      - SUSPEND
      - RESUME
      - ERASE
  operation:
    type: string
    description: The operation to be initiated
    enum:
      - READ_BALANCE
      - UPDATE_BALANCE
      - UPDATE_CONFIG
      - UPDATE_PLAN
      - ERASE_CARD
      - PARK_CARD
      - BLOCK_AND_READ_CARD
  purchaseId:
    maxLength: 48
    minLength: 1
    type: string
    description: The Purchase Identifier. Unique for each purchase.
  issuerId:
    maxLength: 16
    minLength: 1
    type: string
    description: The Card Issuer Identifier. Unique for each card issuer.
  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'
  responseHeader:
    type: object
    required:
      - responseId
      - sessionId
      - statusCode
    properties:
      responseId:
        $ref: '#/definitions/responseId'
      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|
          |116|Unknown card account|
          |117|Unknown device|
          |118|Unknown session|
          |119|Unknown virtual card|          
          |120|Unknown purchase|  
          |121|Unknown request|  
          |221|Device or wallet server not accessible|
          |321|Operation already on-going for this device|
          |322|Time to live of the operation expired|                               
          |432|Operation is not allowed with current card state|     
          |911|Operation failed|          
          |921|Unexpected server error|
      statusMessage:
        type: string
        description: Textual status message
