swagger: '2.0'
info:
  termsOfService: Copyright (c) 2019 GEMALTO. All Rights Reserved
  title: Gemalto TSH Issuer Gateway Auxiliary API
  version: 1.4.3
  description: ''
schemes:
  - https
host: api.dbp.thalescloud.io
basePath: /gtep/igwauxapi
consumes:
  - application/json
produces:
  - application/json
parameters:
  x-correlation-id-header:
    description: 'Unique identifier of a give session (enrolment session or Life Cycle Management session), used to link inbound and outbound **requests** of the same session together'
    in: header
    maxLength: 64
    minLength: 1
    name: x-correlation-id
    required: true
    type: string
  x-issuer-id-header:
    description: Unique identifier used to identify the issuer
    in: header
    maxLength: 10
    minLength: 10
    name: x-issuer-id
    required: true
    type: string
paths:
  /updateCard:
    post:
      x-swagger-router-controller: issuerGatewayDispatcher
      summary: Update funding card information
      description: |
        This method is used by the issuer to update funding card information:<br/>
        - new expiry date value in case of card renewal
        - new PAN and expiry date in case of card replacement

        **The issuer receives a notifyVirtualCardChange per virtualCard (active or suspended) linked to the funding card that is updated.**<br/>
      operationId: updateCard
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/x-correlation-id-header'
        - $ref: '#/parameters/x-issuer-id-header'
        - name: body
          in: body
          description: updateCard request payload
          required: true
          schema:
            $ref: '#/definitions/updateCardReq'
      responses:
        '200':
          description: updateCard response payload
        '400':
          description: 'Bad Request, Invalid request URI or header, or unsupported nonstandard parameter'
          schema:
            $ref: '#/definitions/errorRes'
        '500':
          description: Internal Server Error
      tags:
        - Update Card
  /getCardInfo:
    post:
      x-swagger-router-controller: issuerGatewayDispatcher
      summary: Get virtual card list information
      description: This method can be used to retrieve the list of virtual card(s) that belongs to a funding card.
      operationId: getCardInfo
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/x-correlation-id-header'
        - $ref: '#/parameters/x-issuer-id-header'
        - name: body
          in: body
          description: getCardInfo request payload
          required: true
          schema:
            $ref: '#/definitions/getCardInfoReq'
      responses:
        '200':
          description: getCardInfo response payload
          schema:
            $ref: '#/definitions/getCardInfoRes'
        '400':
          description: 'Bad Request, Invalid request URI or header, or unsupported nonstandard parameter'
          schema:
            $ref: '#/definitions/errorRes'
        '500':
          description: Internal Server Error
      tags:
        - Get Card Info
  /healthCheck:
    get:
      x-swagger-router-controller: issuerGatewayDispatcher
      summary: check if TSH is healthy
      description: This method is used by the Issuer to monitor TSH health
      operationId: healthCheck
      parameters:
        - $ref: '#/parameters/x-correlation-id-header'
        - $ref: '#/parameters/x-issuer-id-header'
      responses:
        '204':
          description: Successful
        '400':
          description: 'Bad Request, Invalid request URI or header, or unsupported nonstandard parameter'
        '500':
          description: Internal Server Error
      tags:
        - Health check
definitions:
  getCardInfoReq:
    type: object
    required:
      - issuerCardRefId
    properties:
      issuerCardRefId:
        $ref: '#/definitions/issuerCardRefId'
  getCardInfoRes:
    type: object
    properties:
      issuerCardRefId:
        $ref: '#/definitions/issuerCardRefId'
      virtualCardList:
        type: array
        items:
          type: object
          properties:
            virtualCardId:
              $ref: '#/definitions/virtualCardId'
            issuerCardRefId:
              $ref: '#/definitions/issuerCardRefId'
            walletProviderId:
              $ref: '#/definitions/walletProviderId'
            walletCardRefId:
              type: string
              description: |-
                Wallet card unique identifier.
                 Not always provided by the Wallet provider.
              minLength: 1
              maxLength: 128
            walletVirtualCardId:
              $ref: '#/definitions/walletVirtualCardId'
            deviceInformation:
              $ref: '#/definitions/deviceInformation'
            provisioningTime:
              type: string
              description: |
                If available, the provisioning time the Virtual card<br/>
                In format **ISO 8601 YYYY-MM-DDThh:mm:ssTZD**
              maxLength: 32
            status:
              type: string
              description: virtual card current status
              maxLength: 32
              enum:
                - DEPLOYMENT_ONGOING
                - SUSPENDED
                - RESUMED
                - DELETED
          required:
            - virtualCardId
            - issuerCardRefId
            - walletProviderId
            - deviceInformation
            - status
    required:
      - issuerCardRefId
  updateCardReq:
    type: object
    properties:
      issuerCardRefId:
        $ref: '#/definitions/issuerCardRefId'
      newIssuerCardRefId:
        type: string
        description: |
          New issuerCardRefId to be updated, provided only if the issuerCardRefId change after a PAN, exp or productId replacement.<br/>
          Note, the **newIssuerCardRefId** is not mandatory and it is preferable to keep the same issuerCardRefId after updateCard<br/>
          This field has been added to the API for issuers that are not able to manage the same identifier following a PAN/exp date update. 
        minLength: 1
        maxLength: 48
      fpanDetails:
        $ref: '#/definitions/fpanDetails'
      publicKeyIdentifier:
        type: string
        maxLength: 32
        minLength: 1
        description: Identifier of the key used to encrypt fpanDetails.<br/>Provided by Thales to Issuer during onboarding.
    required:
      - issuerCardRefId
  updateVirtualCardLinkReq:
    type: object
    properties:
      virtualCardId:
        $ref: '#/definitions/virtualCardId'
      newIssuerCardRefId:
        type: string
        description: The unique identifier of the funding card.
        minLength: 1
        maxLength: 48
      fpanDetails:
        $ref: '#/definitions/fpanDetails'
      publicKeyIdentifier:
        type: string
        maxLength: 32
        minLength: 1
        description: Identifier of the key used to encrypt fpanDetails.<br/>Provided by Thales to Issuer during onboarding.
    required:
      - virtualCardId
      - newIssuerCardRefId
      - fpanDetails
  issuerCardRefId:
    type: string
    maxLength: 48
    description: |
      The unique identifier of the funding card.<br/> This value is generated and managed by the issuer.<br/> This value can be updated in case of funding PAN replacement by the issuer.<br/>
  virtualCardId:
    description: Unique identifier of the virtual card
    type: string
    maxLength: 64
    minLength: 1
  walletProviderId:
    type: string
    description: |
      Wallet Provider identifier, defined by Thales:

      |walletProviderId|Description|
      |-------|-------|
      |FIDESMO_PAY|Fidesmo Pay Wallet|
      |DIGISEQ|Digiseq Wallet|
      |APPLE_PAY|Apple Pay Wallet|
    minLength: 1
    maxLength: 128
  walletVirtualCardId:
    type: string
    description: |-
      Wallet virtual card identifier.
      For ApplePay, it corresponds to the DPANID.
    minLength: 1
    maxLength: 128
  tokenStorageId:
    type: string
    description: Unique token storage identifier
    minLength: 1
    maxLength: 128
  tokenStorageType:
    type: string
    description: |-
      Identifies the type of token storage location, possible values are: <ul><li>PHONE <li>TABLET <li>WATCH <li>COMPUTER<li>REALITY<li>UNKNOWN</ul>
      This list may evolve in the future.
    maxLength: 32
  deviceInformation:
    type: object
    properties:
      tokenStorageId:
        $ref: '#/definitions/tokenStorageId'
      tokenStorageTyoe:
        $ref: '#/definitions/tokenStorageType'
    required:
      - tokenStorageId
  fpanDetails:
    type: string
    description: |
      Old and new FPAN details (for example in case of card renewal).<br/>

      This value is encrypted using the PKCS#7 encryption scheme defined in RFC 2315/5652 using following encryption parameters:<br/>
      * The content encryption algorithm used is AES256/CBC/PKCS7Padding using a randomly generated AES key.
      * The key encryption algorithm is RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256) using the TSH certificate provided during onboarding.
      * The encryption result shall be provided as hexadecimal string.<br/>

      The format of the data is:
        **{
         "oldFPAN": "[0-9]{16,19}",
         "oldExpDate": "MMYY",
         "newFPAN": "[0-9]{16,19}", 
         "newExpDate": "MMYY"
        }**
    maxLength: 8192
  errorRes:
    type: object
    description: Error Information Response
    required:
      - responseCode
    properties:
      responseCode:
        type: number
        description: |
          Error Response code to the request
          |Error code | Description|
          |-------|-------|
          |111|Missing mandatory parameter|
          |112|Bad parameter format|
          |113|Unknown issuer|
          |115|Unknown product|
          |116|Unknown card|
          |119|Unknown Token|
          |163|Product not supported for mobile payment|
          |164|FPAN Provisioning Count Exceeded|
          |166|Invalid FPAN|
          |167|Card already enrolled|
          |321|Operation on token already on-going|
          |322|Time to live of the operation expired|
          |431|Invalid perso data|
          |432|Current token state does not allow this operation|
          |911|Operation failed|
          |921|Unexpected server error|
      errorMessage:
        type: string
        maxLength: 256
        description: Textual error message
tags:
  - name: Health check
  - name: Update Card
  - name: Update Virtual Card Link
  - name: Get Card Info
