swagger: '2.0'
info:
  description: |-
    Copyright (c) 2018 GEMALTO. All Rights Reserved.

    The API follows the HTTP protocol with content type in JSON.

    The messages are encoded with the UTF-8 character set which is the default set defined for JSON.

    **<span style="color:red">Important:</span>** In order to ensure backward compatibility, the connected system shall ignore properly any unused or unrecognized JSON field.

    The API security relies on several layers:
       - transport -> with TLS mutual authentication
       - http -> 
       - application -> with asymmetric keys used to encrypt/decrypt JWE data structures

    As per the swagger file, the requests will be sent to the URL provided by the token requestor concatenated with '/tsh-cof/' and the operation name. 

    Example: <span style="color:DodgerBlue">https://thalesservername:443/path/tsh-cof/healthcheck</span>.
  title: Thales COF Client API
  version: '1.42'
schemes:
  - https
basePath: /tsh-cof
consumes:
  - application/json
produces:
  - application/json
security:
  - BasicAuth: []
parameters:
  xCorrelationId:
    in: header
    description: 'A unique message identifier. It eventually correlates the notification with a request if any. The goal is to help on customer support when needed. '
    name: x-correlation-id
    required: true
    type: string
    minLength: 1
    maxLength: 36
  authorization:
    in: header
    description: |
      Technical identifier pre-defined at on-boarding that identifies the API
      consumer.
      Format shall be the string 'APIKEY' followed by a space and the
      api key value.
      </br> Example: APIKEY c03f88fe-01ba-11e8-ba89-0ed5f89f718b
    name: authorization
    required: true
    type: string
    minLength: 1
    maxLength: 512
  tokenId:
    in: path
    description: The token identifier.
    name: tokenId
    required: true
    maxLength: 128
    type: string
  assetId:
    in: path
    description: The asset identifier.
    name: assetId
    required: true
    maxLength: 128
    type: string
paths:
  /healthcheck:
    get:
      description: This method shall be used to check the server availability.
      operationId: healthcheck
      parameters:
        - $ref: '#/parameters/authorization'
        - $ref: '#/parameters/xCorrelationId'
      responses:
        '204':
          $ref: '#/responses/204'
        '500':
          $ref: '#/responses/500'
        '503':
          $ref: '#/responses/503'
      tags:
        - Healthcheck
      summary: Healthcheck
  /notify-merchant-update:
    post:
      description: |-
        Notify the token requestor about a merchant onboarding update. 

        In case of retryable error returned by the token requestor, the notification will be resent periodically with exponential backoff.
      operationId: notifyMerchantUpdate
      parameters:
        - $ref: '#/parameters/authorization'
        - $ref: '#/parameters/xCorrelationId'
        - in: body
          name: Request
          schema:
            type: object
            required:
              - merchantId
              - scheme
            properties:
              merchantId:
                $ref: '#/definitions/merchantId'
              scheme:
                $ref: '#/definitions/schemeOnboarding'
              trId:
                $ref: '#/definitions/trId'
              mcServiceId:
                $ref: '#/definitions/mcServiceId'
              error:
                $ref: '#/definitions/errorOnboarding'
              lastUpdateTimestamp:
                $ref: '#/definitions/lastUpdateTimestampMerchant'
      responses:
        '204':
          $ref: '#/responses/204'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '404':
          $ref: '#/responses/404'
        '429':
          $ref: '#/responses/429'
        '500':
          $ref: '#/responses/500'
        '503':
          $ref: '#/responses/503'
      tags:
        - Merchant Onboarding
      summary: Notify Merchant Update
  /notify-token-creation:
    post:
      description: |-
        Notify the token requestor about a token creation.

        The notification shares the same 'x-correlation-id' as in the create token request.

        If the tokenization failed, the notification only contains information about the error. No token data is provided.

        In case of retryable error returned by the token requestor, the notification will be resent periodically with exponential backoff. 
      operationId: notifyTokenCreation
      parameters:
        - $ref: '#/parameters/authorization'
        - $ref: '#/parameters/xCorrelationId'
        - in: body
          name: Request
          schema:
            type: object
            required:
              - merchantId
            properties:
              tokenId:
                $ref: '#/definitions/tokenId'
              merchantId:
                $ref: '#/definitions/merchantId'
              cardBin:
                $ref: '#/definitions/cardBin'
              cardLastDigits:
                $ref: '#/definitions/cardLastDigits'
              cardExpiryDate:
                $ref: '#/definitions/cardExpiryDate'
              tokenLastDigits:
                $ref: '#/definitions/tokenLastDigits'
              tokenExpiryDate:
                $ref: '#/definitions/tokenExpiryDate'
              par:
                $ref: '#/definitions/par'
              vProvisionedTokenId:
                $ref: '#/definitions/vProvisionedTokenId'
              cardProduct:
                $ref: '#/definitions/cardProduct'
              error:
                $ref: '#/definitions/error'
              creationTimestamp:
                $ref: '#/definitions/creationTimestamp'
      responses:
        '204':
          $ref: '#/responses/204'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '404':
          $ref: '#/responses/404'
        '429':
          $ref: '#/responses/429'
        '500':
          $ref: '#/responses/500'
        '503':
          $ref: '#/responses/503'
      tags:
        - Token Management
      summary: Notify Token Creation
  /notify-token-update:
    post:
      description: |-
        Notify the token requestor about a network token update. 

        In case of retryable error returned by the token requestor, the notification will be resent periodically with exponential backoff. 

        In case of error and retry, all the notifications regarding a token may not be sent in correct order. The parameter 'lastUpdateTimestamp' shall be used to discard obsolete notifications.

        Most of the time, the TMG sends all the information it has for the token. But there are some edge error cases for which only the 'tokenId' and the 'tokenState' are sent.
      operationId: notifyTokenUpdate
      parameters:
        - $ref: '#/parameters/authorization'
        - $ref: '#/parameters/xCorrelationId'
        - in: body
          name: Request
          schema:
            type: object
            required:
              - tokenId
              - merchantId
            properties:
              tokenId:
                $ref: '#/definitions/tokenId'
              merchantId:
                $ref: '#/definitions/merchantId'
              tokenState:
                $ref: '#/definitions/tokenState'
              cardBin:
                $ref: '#/definitions/cardBin'
              cardLastDigits:
                $ref: '#/definitions/cardLastDigits'
              cardExpiryDate:
                $ref: '#/definitions/cardExpiryDate'
              tokenLastDigits:
                $ref: '#/definitions/tokenLastDigits'
              tokenExpiryDate:
                $ref: '#/definitions/tokenExpiryDate'
              par:
                $ref: '#/definitions/par'
              vProvisionedTokenId:
                $ref: '#/definitions/vProvisionedTokenId'
              deviceBindings:
                $ref: '#/definitions/deviceBindings'
              discardCryptogram:
                $ref: '#/definitions/discardCryptogram'
              cardProduct:
                $ref: '#/definitions/cardProduct'
              creationTimestamp:
                $ref: '#/definitions/creationTimestamp'
              lastUpdateTimestamp:
                $ref: '#/definitions/lastUpdateTimestamp'
      responses:
        '204':
          $ref: '#/responses/204'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '404':
          $ref: '#/responses/404'
        '429':
          $ref: '#/responses/429'
        '500':
          $ref: '#/responses/500'
        '503':
          $ref: '#/responses/503'
      tags:
        - Token Management
      summary: Notify Token Update
  /notify-binding-creation:
    post:
      description: |-
        Notify the token requestor about a device binding creation. 

        In case of retryable error returned by the token requestor, the notification will be resent periodically with exponential backoff.
      operationId: notifyBindingCreation
      parameters:
        - $ref: '#/parameters/authorization'
        - $ref: '#/parameters/xCorrelationId'
        - in: body
          name: Request
          schema:
            type: object
            required:
              - merchantId
              - tokenId
              - deviceId
              - selectedIdvMethod
            properties:
              tokenId:
                $ref: '#/definitions/tokenId'
              deviceId:
                $ref: '#/definitions/deviceId'
              deviceType:
                $ref: '#/definitions/deviceType'
              appType:
                $ref: '#/definitions/appType'
              vProvisionedTokenId:
                $ref: '#/definitions/vProvisionedTokenId'
              selectedIdvMethod:
                $ref: '#/definitions/selectedIdvMethod'
              merchantId:
                $ref: '#/definitions/merchantId'
              creationTimestamp:
                $ref: '#/definitions/creationTimestamp'
      responses:
        '204':
          $ref: '#/responses/204'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '404':
          $ref: '#/responses/404'
        '429':
          $ref: '#/responses/429'
        '500':
          $ref: '#/responses/500'
        '503':
          $ref: '#/responses/503'
      tags:
        - Binding notifications
      summary: Notify Binding Creation
  /notify-binding-update:
    post:
      description: |-
        Notify the token requestor about a device binding update. 

        In case of retryable error returned by the token requestor, the notification will be resent periodically with exponential backoff.
      operationId: notifyBindingUpdate
      parameters:
        - $ref: '#/parameters/authorization'
        - $ref: '#/parameters/xCorrelationId'
        - in: body
          name: Request
          schema:
            type: object
            required:
              - merchantId
              - tokenId
              - deviceId
              - bindingState
              - eventInitiator
            properties:
              tokenId:
                $ref: '#/definitions/tokenId'
              deviceId:
                $ref: '#/definitions/deviceId'
              deviceType:
                $ref: '#/definitions/deviceType'
              appType:
                $ref: '#/definitions/appType'
              bindingState:
                $ref: '#/definitions/bindingState'
              vProvisionedTokenId:
                $ref: '#/definitions/vProvisionedTokenId'
              merchantId:
                $ref: '#/definitions/merchantId'
              eventInitiator:
                $ref: '#/definitions/eventInitiator'
              creationTimestamp:
                $ref: '#/definitions/creationTimestamp'
              lastUpdateTimestamp:
                $ref: '#/definitions/lastUpdateTimestamp'
      responses:
        '204':
          $ref: '#/responses/204'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '404':
          $ref: '#/responses/404'
        '429':
          $ref: '#/responses/429'
        '500':
          $ref: '#/responses/500'
        '503':
          $ref: '#/responses/503'
      tags:
        - Binding notifications
      summary: Notify Binding Update
responses:
  '202':
    description: Accepted
  '204':
    description: No Content
  '400':
    description: Bad request - Not Retryable
  '401':
    description: Unauthorized - Not Retryable
  '404':
    description: Not Found - Not Retryable
  '429':
    description: Too Many Requests - Retryable
  '500':
    description: Internal Server Error - Retryable
  '503':
    description: Service Unavailable - Retryable
securityDefinitions:
  BasicAuth:
    description: |
      Technical identifier pre-defined at on-boarding that identifies the API consumer. Format shall be the string 'APIKEY' followed by a space and the api key value.
      Example: APIKEY c03f88fe-01ba-11e8-ba89-0ed5f89f718b
    type: basic
definitions:
  merchantId:
    type: string
    description: Identifier of the merchant provided by Thales at on-boarding.
    minLength: 1
    maxLength: 128
  tokenId:
    type: string
    description: The token identifier.
    minLength: 1
    maxLength: 128
  vProvisionedTokenId:
    type: string
    description: Specific to Visa. Another token identifier that shall be used only with Visa Cloud Token Framework.
    minLength: 1
    maxLength: 36
  deviceId:
    type: string
    description: The unique device identifier.
    minLength: 1
    maxLength: 24
  tokenLastDigits:
    type: string
    maxLength: 5
    description: The token last digits.
    example: '5589'
  tokenExpiryDate:
    type: string
    maxLength: 4
    description: The token expiry date in format MMYY. This information can be missing. It is intended for display only at this step.<br>Rely on token expiry date in create transaction response for storage.
    example: '1022'
  cardBin:
    type: string
    description: The card bin returned by the scheme, just available for VISA and Mastercard SCOF.
    minLength: 6
    maxLength: 8
    example: '453421'
  cardLastDigits:
    type: string
    maxLength: 5
    description: The card last digits.
    example: '2366'
  cardExpiryDate:
    type: string
    maxLength: 4
    description: The card expiry date in format MMYY.
    example: '0420'
  issuerName:
    type: string
    maxLength: 128
    description: The card issuer name.
    example: Bank Name
  supportVisaCTF:
    type: boolean
    description: Indicate if Visa Cloud Token Framework is available.
    example: true
  cardDescription:
    type: string
    maxLength: 256
    description: The card description.
    example: 'Card description (premium, basic, etc.).'
  cardType:
    type: string
    description: The card type.
    maxLength: 32
    enum:
      - CREDIT
      - DEBIT
      - PREPAID
      - UNKNOWN
    example: DEBIT
  scheme:
    type: string
    description: The card primary scheme.
    maxLength: 32
    enum:
      - MASTERCARD
      - VISA
      - AMEX
      - DISCOVER
      - ELO
    example: MASTERCARD
  deviceBindings:
    type: array
    description: The list of device identifiers bound to the token as per Visa Cloud Token Framework.
    items:
      $ref: '#/definitions/deviceId'
    uniqueItems: true
  termsAndConditionsUrl:
    type: string
    maxLength: 512
    description: Card issuer terms and conditions URL.
    example: 'https://bank.com/tncs.html'
  privacyPolicyUrl:
    type: string
    maxLength: 512
    description: Card issuer privacy policy URL.
    example: 'https://bank.com/privacyPolicy.html'
  cardProduct:
    type: object
    description: Information about the card product.
    required:
      - cardType
      - scheme
    properties:
      issuerName:
        $ref: '#/definitions/issuerName'
      cardType:
        $ref: '#/definitions/cardType'
      scheme:
        $ref: '#/definitions/scheme'
      supportVisaCTF:
        $ref: '#/definitions/supportVisaCTF'
      cardDescription:
        $ref: '#/definitions/cardDescription'
      cardArts:
        $ref: '#/definitions/cardArts'
      termsAndConditionsUrl:
        $ref: '#/definitions/termsAndConditionsUrl'
      privacyPolicyUrl:
        $ref: '#/definitions/privacyPolicyUrl'
  cardArts:
    type: object
    properties:
      foregroundColor:
        type: string
        maxLength: 6
        description: 'Color used for the text displayed on the card (last digits, expiry date). Hexadecimal RGB color format.'
        example: 7FB8C8
      backgroundColor:
        type: string
        maxLength: 6
        description: Color used for card background. Hexadecimal RGB color format.
        example: 7FB8C9
      cardBackgroundImageId:
        type: string
        maxLength: 128
        description: Asset identifier of the card background image. It doesn't contain the issuer/brand/co-brand logo.
        example: 2ee5c858-a6a4-43f1-a503-ffde6c41fad9
      issuerLogoId:
        type: string
        maxLength: 128
        description: Asset identifier of the issuer logo.
        example: 1fd8594c-5284-4aeb-bb73-6129c1d6cdb2
      brandLogoId:
        type: string
        maxLength: 128
        description: Asset identifier of the primary brand logo.
        example: 623046b7-4a8f-4550-bca8-45b38c9498a3
      cobrandLogoId:
        type: string
        maxLength: 128
        description: Asset identifier of the cobrand logo.
        example: 5548eb95-3aee-4bb8-9abf-38a7ab2c1cf3
      completeCardImageId:
        type: string
        maxLength: 128
        description: Asset identifier of the complete card image. Shall be preferred over the other assets when present.
        example: 15ac4371-dcb9-4310-867e-b12338970276
      cardIconId:
        type: string
        maxLength: 128
        description: Asset identifier of the card icon.
        example: 14e3044fa-949e-4900-800f-88b8fc6cc3d5
      cardImageUrl:
        type: string
        maxLength: 512
        description: 'HTTP location of the card image. If present, no other identifier is provided and getAsset operation is not needed.'
        example: 'https://stage.assets.mastercard.com/card-art/combined-image-asset/MyBank-mastercard.png'
  par:
    type: string
    maxLength: 29
    description: Payment Account Reference returned by the Scheme TSP.
    example: 5001a9f027e5629d11e3949a0800a
  tokenState:
    type: string
    maxLength: 64
    description: Token state.</br>PCI token state can only be 'ACTIVE' or 'DELETED'.
    enum:
      - ACTIVE
      - SUSPENDED
      - DELETED
    example: ACTIVE
  discardCryptogram:
    type: boolean
    description: 'If present and set to ''true'', all pre-fetched cryptograms linked to the token shall be discarded as they are no more valid due to the token update.'
    default: false
  creationTimestamp:
    type: string
    maxLength: 64
    description: Token or binding creation timestamp compliant with ISO 8601.
    example: '2017-11-10T09:08:24.479Z'
  lastUpdateTimestamp:
    type: string
    maxLength: 64
    description: Token or binding last update timestamp compliant with ISO 8601.
    example: '2017-11-13T11:012:41.165Z'
  lastUpdateTimestampMerchant:
    type: string
    maxLength: 64
    description: Last update timestamp compliant with ISO 8601.
    example: '2017-11-13T11:012:41.165Z'
  bindingState:
    type: string
    maxLength: 64
    description: Binding state.
    enum:
      - DELETED
    example: DELETED
  deviceType:
    type: string
    description: The device type.
    maxLength: 32
    enum:
      - PHONE
      - TABLET
      - WATCH
      - TV
      - WEARABLE_DEVICE
    example: PHONE
  appType:
    type: string
    description: The device type.
    maxLength: 32
    enum:
      - IOS
      - ANDROID
      - WEB
    example: ANDROID
  selectedIdvMethod:
    type: string
    description: The ID&V method selected to bind the device.
    maxLength: 32
    enum:
      - OTP_SMS
      - OTP_EMAIL
      - OTP_ONLINE_BANKING
      - APP_TO_APP
      - OUTBOUND_CALL
      - CUSTOMER_SERVICE
      - NONE
      - UNKNOWN
    example: APP_TO_APP
  eventInitiator:
    type: string
    description: The initiator of the event. For example a delete binding can be initiated by the scheme or by the app in the device.
    maxLength: 32
    enum:
      - TSP
      - APP
    example: TSP
  trId:
    type: string
    description: |-
      The Token Requestor Identifier generated by the scheme for that merchant.
      In case of Mastercard Secure Card-On-File program, this field is not returned, see 'mcServiceId' instead.
    minLength: 1
    maxLength: 32
    example: '40000000080'
    title: ''
  mcServiceId:
    type: string
    description: 'Token Requestor Id for SCOF solution, equivalent to the TRID. It is assigned by Mastercard to entity for which tokens are created. '
    minLength: 1
    maxLength: 256
  schemeOnboarding:
    type: string
    description: The card primary scheme.
    maxLength: 32
    enum:
      - MASTERCARD
      - VISA
    example: VISA
  error:
    type: object
    description: Information about the error in case the token is not created.
    properties:
      errorCode:
        type: string
        maxLength: 128
        description: |-
          The error code as specified in below table.

          -----------------
          |Error Code|Description|
          |-------|-------|
          |NON_RETRYABLE_ERROR|Generic code for all non retryable errors returned by the TMG.|
          |RETRYABLE_ERROR|Generic code for all retryable errors returned by the TMG.|
          |TSP_NON_RETRYABLE_ERROR|Generic code for all non retryable errors returned by the TSP.|
          |TSP_RETRYABLE_ERROR|Generic code for all retryable errors returned by the TSP.|
          |TSP_ABORTED|The TSP aborted the token creation process.|
          |INVALID_PAN_DATA|The PAN data is invalid.|
          |PAN_NOT_ELIGIBLE|The Issuer considers the PAN as not eligible for tokenization.|
          |ISSUER_DECLINED|The Issuer declined the tokenization.|
          |EXPIRED|The session timeout expired.|
          -----------------
        example: TSP_NON_RETRYABLE_ERROR
      errorDetails:
        type: string
        maxLength: 256
        description: Additional information about the error. This optional parameter has no specific format as it depends on the different TSP API. It is sent for logging and troubleshooting purpose.
    required:
      - errorCode
  errorOnboarding:
    type: object
    description: Information about the error in case a problem occurs when a merchant is onboarded.
    properties:
      errorCode:
        type: string
        maxLength: 128
        description: |-
          The error code as specified in below table.

          -----------------
          |Error Code|Description|
          |-------|-------|
          |NON_RETRYABLE_ERROR|Generic code for all non retryable errors returned by the TMG.|
          |RETRYABLE_ERROR|Generic code for all retryable errors returned by the TMG.|
          |TSP_NON_RETRYABLE_ERROR|Generic code for all non retryable errors returned by the TSP.|
          |TSP_RETRYABLE_ERROR|Generic code for all retryable errors returned by the TSP.|
          -----------------
        example: TSP_NON_RETRYABLE_ERROR
      errorDetails:
        type: string
        maxLength: 256
        description: Additional information about the error. This optional parameter has no specific format as it depends on the different TSP API. It is sent for logging and troubleshooting purpose.
    required:
      - errorCode
tags:
  - name: Healthcheck
  - name: Merchant Onboarding
  - name: Token Management
  - name: Binding notifications
  
