swagger: '2.0'
info:
  title: Thales TSH Transit API - TSH to WS
  description: Thales TSH Transit API - TSH to WS
  termsOfService: Copyright (c) 2019 Thales. All Rights Reserved
  version: 1.0.8
paths:
  /sendScript:
    post:
      summary: Request to send a script to a device
      description: This method is used by TSH to provide a script to a device.
      operationId: sendScript
      produces:
        - application/json
      consumes:
        - application/json
      parameters:
        - $ref: '#/parameters/podHeader'
        - in: body
          name: body
          schema:
            $ref: '#/definitions/sendScriptReq'
          description: sendScript request payload
          required: true
      responses:
        '200':
          description: sendScript response payload
          schema:
            $ref: '#/definitions/sendScriptRes'
        '500':
          description: Internal Server Error
  /updateCard:
    post:
      summary: Request to update a digital card
      description: This method is used by TSH to request to update a digital card.
      operationId: updateCard
      produces:
        - application/json
      consumes:
        - application/json
      parameters:
        - $ref: '#/parameters/podHeader'
        - in: body
          name: body
          schema:
            $ref: '#/definitions/updateCardReq'
          description: updateCard request payload
          required: true
      responses:
        '200':
          description: updateCard response payload
          schema:
            $ref: '#/definitions/updateCardRes'
        '500':
          description: Internal Server Error
  /getTaskStatus:
    post:
      summary: Request to get the status of a task
      description: This method is used by TSH to request a task status.
      operationId: getTaskStatus
      produces:
        - application/json
      consumes:
        - application/json
      parameters:
        - $ref: '#/parameters/podHeader'
        - in: body
          name: body
          schema:
            $ref: '#/definitions/getTaskStatusReq'
          description: getTaskStatus request payload
          required: true
      responses:
        '200':
          description: getTaskStatus response payload
          schema:
            $ref: '#/definitions/getTaskStatusRes'
        '500':
          description: Internal Server Error
definitions:
  sendScriptReq:
    type: object
    properties:
      requestHeader:
        $ref: '#/definitions/requestHeader'
      taskId:
        $ref: '#/definitions/taskId'
      walletCardId:
        $ref: '#/definitions/walletCardId'
      seId:
        $ref: '#/definitions/seId'
      apduCommands:
        $ref: '#/definitions/apduCommands'
    required:
      - requestHeader
      - taskId
      - walletCardId
      - seId
      - apduCommands
  requestHeader:
    type: object
    properties:
      requestId:
        $ref: '#/definitions/requestId'
      sessionId:
        $ref: '#/definitions/sessionId'
      generationDateTime:
        $ref: '#/definitions/generationDateTime'
    required:
      - requestId
      - sessionId
  requestId:
    type: string
    description: Unique request identifier
    minLength: 1
    maxLength: 48
  sessionId:
    type: string
    description: Unique session identifier used to trace the calls across systems during a use case.
    minLength: 1
    maxLength: 48
  generationDateTime:
    type: string
    description: |-
      Date time representing when the request or response has been generated.<br/>RFC3339 format. <br/>Example:
       - 2018-12-24T17:32:28Z
    format: date-time
  taskId:
    type: string
    description: Unique task identifier used to correlate a callback to a request.
    minLength: 1
    maxLength: 64
  walletCardId:
    type: string
    description: The Wallet Card Identifier. Unique for each wallet card.
    minLength: 1
    maxLength: 64
  seId:
    type: string
    description: Secure Element Identifier
    pattern: '([0-9a-fA-F][0-9a-fA-F]){1,24}'
  apduCommands:
    type: array
    description: List of APDU commands to send to a secure element.
    items:
      type: object
      properties:
        data:
          type: string
          description: 'APDU command to execute on SE, encoded in Hex string.'
          pattern: '^([0-9a-fA-F]{2})*$'
          maxLength: 512
        messageId:
          type: string
          description: ID of the command to execute
          minLength: 1
          maxLength: 64
        messageName:
          type: string
          description: Descriptive name of the command that needs to be executed.
          minLength: 1
          maxLength: 100
      required:
        - data
        - messageId
  sendScriptRes:
    type: object
    properties:
      responseHeader:
        type: object
        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|         
              |119|Unknown virtual card|                    
              |321|Operation already on-going for this device|         
              |432|Operation is not allowed with current card state|   
              |911|Operation failed|          
              |921|Unexpected server error|
          statusMessage:
            type: string
            description: Textual status message
        required:
          - responseId
          - sessionId
          - statusCode
    required:
      - responseHeader
  responseId:
    type: string
    description: Unique response identifier
    minLength: 1
    maxLength: 48
  updateCardReq:
    type: object
    properties:
      requestHeader:
        $ref: '#/definitions/requestHeader'
      taskId:
        $ref: '#/definitions/taskId'
      walletCardId:
        $ref: '#/definitions/walletCardId'
      seId:
        $ref: '#/definitions/seId'
      operation:
        $ref: '#/definitions/operation'
      cardDescriptor:
        $ref: '#/definitions/cardDescriptor'
    required:
      - requestHeader
      - taskId
      - walletCardId
      - seId
      - operation
  operation:
    type: string
    enum:
      - SUSPEND
      - RESUME
      - DELETE
      - METADATA_UPDATE
      - REDIRECT
      - ERASE
    description: 'Operation to perform on a digital card.</br><li>SUSPEND: for suspending the digital card, usually GP lock is performed on SE<li>RESUME: for resuming the digital card, usually GP unlock is performed on SE<li>DELETE: for deleting the digital card and related instances in SE<li>METADATA_UPDATE: for updating the digital card metadata.</br>cardDescriptor is provided for this operation.<li>REDIRECT: used to notify the device to connect to TSH to fetch some commands using getDeviceCommands API.<li>ERASE: for completely removing the digital card from device and server as defined in GDPR.'
  cardDescriptor:
    type: object
    description: The card descriptor which contains various metadata.</br>
    properties:
      appletCurrencyCode:
        type: string
        description: The apple currency code.</br> It is specified as 3 letters code (ISO4217)
        minLength: 3
        maxLength: 3
      displayCardNumber:
        type: string
        description: 'The card number to be displayed on the wallet.<br/> If it''s not provided, cardId will be used.'
        minLength: 1
        maxLength: 16
      cardholderName:
        type: string
        description: The card holder to be displayed on the wallet.
        minLength: 1
        maxLength: 128
      cardArtManifest:
        $ref: '#/definitions/cardArtManifest'
      labelColor:
        type: string
        description: Color of overlaying text
        pattern: '^rgb([0-9]{1,3},[0-9]{1,3},[0-9]{1,3})$'
      shortDescription:
        type: string
        description: A short description of the card.
        maxLength: 32
      longDescription:
        type: string
        description: A longer description of the card.
        maxLength: 64
      privacyPolicyURL:
        type: string
        description: URL pointing to issuer privacy policy
        maxLength: 128
      termsAndConditionsURL:
        type: string
        description: URL pointing to card terms and conditions
        maxLength: 128
      contactWebsite:
        type: string
        description: Customer service website of the issuer
        maxLength: 128
      contactEmail:
        type: string
        description: Customer service email address of the issuer
        maxLength: 32
      contactNumber:
        type: string
        description: 'Customer service phone number of the issuer.</br> This number is provided in standard, international format with country code'
        maxLength: 32
      contactName:
        type: string
        description: Customer service contact name of the issuer
        maxLength: 128
      cardActions:
        type: object
        properties:
          minLoadedBalance:
            type: number
            description: Minimum value amount a card can contain after applying a top-up action
          maxLoadedBalance:
            type: number
            description: Maximum value amount a card can contain after using a top-up action
          minLoadAmount:
            type: number
            description: Minimum amount that can be added during a top-up action per transaction
          maxLoadAmount:
            type: number
            description: Maximum amount that can be added during a top-up action per transaction
        required:
          - maxLoadedBalance
          - minLoadAmount
      mobileApp:
        type: object
        properties:
          identifier:
            type: string
            description: Identifier of the mobile application
            maxLength: 128
          action:
            type: string
            description: Mobile application native action.</br> Used for deep linking
            maxLength: 128
          intentExtraText:
            type: string
            description: Mobile application native intent extra text.</br> Used for deep linking
            maxLength: 128
        required:
          - identifier
  cardArtManifest:
    type: array
    description: Array of GUIDs required to build card art.</br> Each cart art can be retrieved using getAsset API with corresponding GUID.
    items:
      type: string
      maxLength: 64
  updateCardRes:
    type: object
    properties:
      responseHeader:
        type: object
        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|              
              |119|Unknown virtual card|     
              |321|Operation already on-going for this device|       
              |432|Operation is not allowed with current card state|   
              |911|Operation failed|          
              |921|Unexpected server error|
          statusMessage:
            type: string
            description: Textual status message
        required:
          - responseId
          - sessionId
          - statusCode
    required:
      - responseHeader
  getTaskStatusReq:
    type: object
    properties:
      requestHeader:
        $ref: '#/definitions/requestHeader'
      taskId:
        $ref: '#/definitions/taskId'
      seId:
        $ref: '#/definitions/seId'
    required:
      - requestHeader
      - taskId
      - seId
  getTaskStatusRes:
    type: object
    properties:
      responseHeader:
        type: object
        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|              
              |121|Unknown task|               
              |911|Operation failed|          
              |921|Unexpected server error|
          statusMessage:
            type: string
            description: Textual status message
        required:
          - responseId
          - sessionId
          - statusCode
      taskStatus:
        type: string
        enum:
          - PROCESSING
          - COMPLETED
          - FAILED
    required:
      - responseHeader
parameters:
  podHeader:
    name: x-pod
    in: header
    description: HTTP header identifying the pod and corresponding DNS hostname of the load balancer from which traffic is coming.</br> Subsequent API calls should be sent to this pod.
    required: true
    type: string
    maxLength: 128
