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
basePath: /issuer/igwauxapi
consumes:
  - application/json
produces:
  - application/json
parameters:
  x-correlation-id-header:
    description: |
      Unique identifier of a give session (enrolment session , Life Cycle Management session and other operation), used to link inbound and outbound **requests** of the same session together<br/>
    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:
  /notifyVirtualCardChange:
    post:
      x-swagger-router-controller: issuerGatewayDispatcher
      summary: notify issuer about any virtual card (token) change
      description: |-
        This method is used by TSH to notify issuer in case a virtual card has been updated due to:
        - state change (activated/suspended/resumed/deleted)
        - belonging card updated
      operationId: notifyVirtualCardChange
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/x-correlation-id-header'
        - $ref: '#/parameters/x-issuer-id-header'
        - name: body
          in: body
          description: notifyVirtualCardChange request payload
          required: true
          schema:
            $ref: '#/definitions/notifyVirtualCardChangeReq'
      responses:
        '200':
          description: Successful
        '400':
          description: 'Bad Request, Invalid request URI or header, or unsupported nonstandard parameter'
          schema:
            type: object
            description: Error Information Response
            required:
              - responseCode
            properties:
              responseCode:
                type: number
                description: |
                  Error Response code to the request
                  |Error code | Description|
                  |-------|-------|
                  |911|Operation failed|
                  |921|Unexpected server error|
              errorMessage:
                maxLength: 256
                type: string
                description: Textual error message
        '500':
          description: Internal Server Error
      tags:
        - Notify Virtual Card Change
  /healthCheck:
    get:
      x-swagger-router-controller: issuerGatewayDispatcher
      summary: check if Issuer is healthy
      description: This method is used by TSH to monitor Issuer 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
  /requestCoBadgeDigitization:
    post:
      responses:
        '200':
          description: requestCoBadgeDigitization response payload
          schema:
            $ref: '#/definitions/requestCoBadgeDigitizationRes'
        '400':
          description: 'Bad Request, Invalid request URI or header, or unsupported nonstandard parameter'
          schema:
            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|
                  |116|Unknown Card|158|Card is expired|
                  |159|Card is supended|
                  |161|Invalid CVV2|
                  |166|Invalid FPAN|
                  |911|Operation failed|
                  |921|Unexpected server error|
              errorMessage:
                maxLength: 256
                type: string
                description: Textual error message
        '500':
          description: Internal Server Error
      summary: request cobadge card digitization to the Issuer
      description: |
        This method is used by TSH exclusively to request the digitization of a cobadge card.

        **TSH will provide either cipheredCardInfo or (exclusive) cipheredTokenInfo or (exclusive) issuerCardRefId**, depending on inputs from the Wallet provider.

        The Issuer can still approve or reject the request. But the latter case will mostly happen in some limit, error cases, since the Wallet Provider will always trigger the cobadge digitization flow only in the case the digitization on the primary flow is approved.

        In some exceptional error case scenarios that involve a retry from the end user or the Wallet Provider, the Issuer shall expect to receive the same request several times. Only the latest request has to be taken into account.
      operationId: requestCoBadgeDigitization
      produces:
        - application/json
      parameters:
        - in: header
          name: x-correlation-id
          type: string
          description: 'Unique identifier of a give session (enrolment session , Life Cycle Management session and other operation), used to link inbound and outbound **requests** of the same session together<br/>'
          maxLength: 64
          minLength: 1
          required: true
        - in: header
          name: x-issuer-id
          type: string
          maxLength: 10
          minLength: 10
          description: Unique identifier used to identify the issuer
          required: true
        - in: body
          name: body
          schema:
            $ref: '#/definitions/requestCoBadgeDigitizationReq'
          description: requestCoBadgeDigitization request payload
      tags:
        - Request Cobadge Card Digitization
definitions:
  requestCoBadgeDigitizationReq:
    type: object
    properties:
      cipheredCardInfo:
        $ref: '#/definitions/cipheredCardInfo'
      cipheredTokenInfo:
        $ref: '#/definitions/cipheredTokenInfo'
      publicKeyIdentifier:
        type: string
        maxLength: 32
        minLength: 1
        description: Identifier of the key used to encrypt cipheredCardInfo.<br/>Provided by Issuer to Thales during onboarding.
      issuerCardRefId:
        $ref: '#/definitions/issuerCardRefId'
      walletProviderId:
        $ref: '#/definitions/walletProviderId'
      walletCardRefId:
        $ref: '#/definitions/walletCardRefId'
      deviceInformation:
        $ref: '#/definitions/deviceInformation'
    required:
      - walletProviderId
      - deviceInformation
  requestCoBadgeDigitizationRes:
    type: object
    properties:
      issuerCardRefId:
        $ref: '#/definitions/issuerCardRefId'
      paymentAccountReference:
        $ref: '#/definitions/paymentAccountReference'
      cipheredDomesticCard:
        $ref: '#/definitions/cipheredDomesticCard'
      publicKeyIdentifier:
        type: string
        minLength: 1
        maxLength: 32
        description: Identifier of the key used to encrypt cipheredDomesticCard.<br/>Provided by Thales to Issuer during onboarding.
    required:
      - issuerCardRefId
  notifyVirtualCardChangeReq:
    type: object
    properties:
      issuerCardRefId:
        $ref: '#/definitions/issuerCardRefId'
      virtualCardId:
        $ref: '#/definitions/virtualCardId'
      walletProviderId:
        $ref: '#/definitions/walletProviderId'
      walletCardRefId:
        $ref: '#/definitions/walletCardRefId'
      walletVirtualCardId:
        type: string
        description: 'Wallet virtual card identifier.<br/>For ApplePay, it corresponds to the auxiliary DPANID.'
        minLength: 1
        maxLength: 128
      primaryWalletVirtualCardId:
        type: string
        description: 'Primary wallet virtual card identifier.<br/>For ApplePay, it corresponds to the primary DPANID.'
        minLength: 1
        maxLength: 128
      tokenStorageId:
        $ref: '#/definitions/tokenStorageId'
      isPrimary:
        type: boolean
        description: |-
          It is a boolean information that inform if the virtual card is a primary virtual card or if it is an auxiliary virtual card.
          Always set to false in this API.
        example: false
      action:
        type: string
        description: |-
          This corresponds to the action performed on the token

          Here are the possible values:
          - ACTIVATE: When the virtual card is activated after provisioning.
          - SUSPEND: When the active virtual card is suspended.
          - RESUME: When the suspended virtual card is re-activated.
          - DELETE: When the virtual card deleted.
          - UPDATE: When the funding PAN value is updated (ex: card renewal).
          - ERASE: When a virtual card is erased following a GDPR action.
        maxLength: 128
        enum:
          - ACTIVATE
          - SUSPEND
          - RESUME
          - DELETE
          - UPDATE
          - ERASE
      tokenInfo:
        type: string
        maxLength: 8196
        minLength: 1
        description: |
          Token information in JSON.
          This field is conditional to the TSP and provided only during enrolment.

          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 either RSAES-PKCS1-v1_5 (RSA/NONE/PKCS1Padding) or RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256), using the certificate provided during onboarding.<br/>
          The key encryption algorithm is defined during onboarding and is by default (if ommitted) the RSA/NONE/PKCS1Padding for legacy purpose.<br/>
          It is recommended to configure RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256) for new issuers.
          * The encryption result is then encoded using base64.<br/>
          * The public key length in the certificate can be 2048-bit or 4096-bit.


          Once deciphered, the cardInfo contains the following information:<br/>

          |JSON field parameter name |description|MOC|Length|
          |--------------------------|------------|----|-------|
          |pan |The token PAN.|M|Up to 19|
          |exp |The expiry date in the format MMYY.|M|4|
      publicKeyIdentifier:
        type: string
        maxLength: 32
        minLength: 1
        description: Identifier of the key used to encrypt tokenInfo.<br/>Provided by Issuer to Thales during onboarding.
      errorCode:
        type: number
        description: |-
          Error code provided in case of operation failure initiated by the issuer<br/>
          |reason code |description|
          |------------|-----------|
          |113 |Unknown issuer|
          |115 |Unknown product|
          |119 |Unknown Token|
          |221 |The device was not reachable after retries|
          |322 |Time to live of the operation expired|
          |911 |Operation failed|
          |921 |Unexpected error|

          This list is not exhaustive. Error codes not listed shall be considered as a generic error.
      source:
        type: string
        description: The source actor that initiated the state change
        maxLength: 32
        enum:
          - WALLET
          - ISSUER
    required:
      - issuerCardRefId
      - virtualCardId
      - walletProviderId
      - tokenStorageId
      - isPrimary
      - source
  deviceInformation:
    type: object
    properties:
      tokenStorageId:
        $ref: '#/definitions/tokenStorageId'
      tokenStorageType:
        $ref: '#/definitions/tokenStorageType'
    required:
      - tokenStorageId
  cipheredCardInfo:
    maxLength: 8196
    minLength: 1
    type: string
    description: |
      The card information in JSON, 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 either RSAES-PKCS1-v1_5 (RSA/NONE/PKCS1Padding) or RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256), using the certificate provided during onboarding.<br/>
      The key encryption algorithm is defined during onboarding and is by default (if ommitted) the RSA/NONE/PKCS1Padding for legacy purpose.<br/>
      It is recommended to configure RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256) for new issuers.
      * The encryption result is then encoded using base64.<br/>
      * The public key length in the certificate can be 2048-bit or 4096-bit.

      Once deciphered, the cardInfo contains the following information:<br/>

      |JSON field parameter name |description |MOC |Length |
      |--------------------------|------------|----|-------|
      |fpan |The funding pan to digitize |M |Up to 19 |
      |exp |The expiry date in the format MMYY |O |4 |
      |cvv |Depending of the OEM and scheme, this value is provided or not |O |3 or 4 |

      <br/>

      **Examples:**

      ``` javascript
        Example 1
        {
          "fpan":"1234567891234567",
          "exp":"1218",
        }

        Example 2
        {
          "fpan":"1234567891234567",
          "exp":"1218",
          "cvv":"765"
        }
  cipheredTokenInfo:
    maxLength: 8196
    minLength: 1
    type: string
    description: |
      The encrypted data contains the original token information used with primary TSP (Token for Token provisioning).
      <br/>This is only applicable for **HCE Wallet**.
      <br/>
      <br/>
      The original token information in JSON is encrypted using the PKCS#7 encryption. See encryption of **cipheredCardInfo** for more details.
      <br/>
      <br/>
      Once deciphered the tokenInfo contains the following information:<br/>
      <br/>
      <br/>
      |JSON field parameter name |description |MOC |Length|
      |--------------------------|------------|----|-------|
      |originalTokenRequestorId |Token Requestor Identifier of the original token provided and allocated by Scheme TSP |O |Up to 11 |
      |originalTokenId | The original token identifier as defined by the Scheme TSP.<br>For VISA (VTS) it corresponds to **vProvisionedTokenID**<br>Mandatory if originalToken is not provided. |C |Up to 64 |
      |originalToken |The original token used to request the digitization with primary TSP<br>Mandatory if originalTokenId is not provided. |C |Up to 19 |
  cipheredDomesticCard:
    maxLength: 8196
    minLength: 1
    type: string
    description: |
      The domestic card information in JSON, 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 either RSAES-PKCS1-v1_5 (RSA/NONE/PKCS1Padding) or RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256), using the certificate provided during onboarding.<br/>
      The key encryption algorithm is defined during onboarding and is by default (if ommitted) the RSA/NONE/PKCS1Padding for legacy purpose.<br/>
      It is recommended to configure RSA/NONE/OAEPWithSHA256AndMGF1Padding (with MGF1 using SHA-256) for new issuers.
      * The encryption result is then encoded using base64.<br/>
      * The public key length in the certificate can be 2048-bit or 4096-bit.

      Once deciphered, the payload shall contain the following information:<br/>

      |JSON field parameter name |description |MOC |Length |
      |--------------------------|------------|----|-------|
      |fpan |The domestic funding pan to digitize |M |Up to 19 |
      |exp |The expiry date in the format MMYY |O |4 |      

      <br/>

      **Examples:**
      ``` javascript        
        {
          "fpan":"1234567891234567",
          "exp":"1228",
      }
    x-stoplight:
      id: 993452fe10ece
  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.
  walletProviderId:
    type: string
    description: |
      Wallet Provider identifier, defined by Thales:

      |walletProviderId|Description|
      |-------|-------|
      |APPLE_PAY|Apple Pay Wallet|
      |ANDROID_PAY|Google Pay Wallet|
      |SPAYHCE|Samsung Pay Wallet|
    minLength: 1
    maxLength: 128
  walletCardRefId:
    type: string
    description: |-
      Card unique identifier defined by the Wallet Provider or the primary TSP.<br/>For ApplePay, it corresponds to the FPANID.<br/>
      For Fidesmo/Digiseq, it corresponds to the card identifier provided by the primary TSP.
    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
  paymentAccountReference:
    type: string
    description: The payment account reference value to associate with the token.<br/>The usage of this optional field depends on the solution and the personalization profile.
    minLength: 58
    maxLength: 58
  virtualCardId:
    description: Unique identifier of the virtual card
    type: string
    maxLength: 64
    minLength: 1
  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|
          |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:
        maxLength: 256
        type: string
        description: Textual error message
host: issuer.host.com
tags:
  - name: Health Check
  - name: Notify Virtual Card Change
  - name: Request Cobadge Card Digitization
