swagger: '2.0'
info:
  contact:
    name: vincent.lemonnier@thalesgroup.com
  description: Gemalto TSH Transaction Notification API
  termsOfService: Copyright (c) 2017 GEMALTO. All Rights Reserved
  title: Gemalto TSH Transaction Notification API
  version: 2.2.2
schemes:
  - https
host: api.dbp.thalescloud.io
basePath: /tns-dispatcher/tsh/tnapi/v2.0
consumes:
  - application/json
produces:
  - application/json
parameters:
  transactionIdPath:
    type: string
    in: path
    maxLength: 64
    minLength: 1
    required: true
    description: Transaction identifier
    name: transactionId
  x-correlation-id-header:
    description: Unique identifier used to trace function calls across systems
    in: header
    maxLength: 64
    minLength: 1
    name: x-correlation-id
    required: true
    type: string
  x-wallet-indicator-header:
    description: |
      Indicator used to specify which wallet type performed the transaction.      
      Possible values are:
        * 1 for Apple Pay
        * 2 for Google Pay
        * 3 for Samsung Pay
        * 4 for Huawei Pay
        * 5 for HCE Issuer Wallets
    in: header
    name: x-wallet-indicator
    required: false
    type: number
paths:
  '/token-transactions/{transactionId}':
    put:
      x-swagger-router-controller: tokenRequestorDispatcher
      summary: Submit token transaction details
      description: This method is used by TSP to send the detailed result of a transaction from a token
      operationId: notifyTokenTransaction
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/x-correlation-id-header'
        - $ref: '#/parameters/x-wallet-indicator-header'
        - $ref: '#/parameters/transactionIdPath'
        - name: body
          in: body
          description: notifyTransaction request payload
          required: true
          schema:
            $ref: '#/definitions/notifyTokenTransactionReq'
      responses:
        '204':
          description: successful
        '400':
          description: 'Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.</br> Possible error codes are 111, 112, 113, 119, 911, 921'
          schema:
            $ref: '#/definitions/errorRes'
        '500':
          description: Internal Server Error
      tags:
        - Token Transactions
  '/card-transactions/{transactionId}':
    put:
      x-swagger-router-controller: tokenRequestorDispatcher
      summary: Submit card transaction details
      description: This method is used by TSP to send the detailed result of a transaction from a funding card
      operationId: notifyCardTransaction
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/x-correlation-id-header'
        - $ref: '#/parameters/transactionIdPath'
        - name: body
          in: body
          description: notifyTransaction request payload
          required: true
          schema:
            $ref: '#/definitions/notifyCardTransactionReq'
      responses:
        '204':
          description: successful
        '400':
          description: 'Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.</br> Possible error codes are 111, 112, 113, 116, 911, 921'
          schema:
            $ref: '#/definitions/errorRes'
        '500':
          description: Internal Server Error
      tags:
        - Card Transactions
definitions:
  notifyTokenTransactionReq:
    type: object
    required:
      - issuerId
      - tokenId
      - transactionInfo
    properties:
      issuerId:
        $ref: '#/definitions/issuerId'
      tokenId:
        description: |
          Unique token identifier.<br/>For Apple Pay International Card Scheme transactions, ICS DPANID shall be used.
        $ref: '#/definitions/tokenId'
      transactionInfo:
        $ref: '#/definitions/tokenTransactionInfo'
  notifyCardTransactionReq:
    type: object
    required:
      - issuerId
      - cardId
      - transactionInfo
    properties:
      issuerId:
        $ref: '#/definitions/issuerId'
      cardId:
        $ref: '#/definitions/cardId'
      transactionInfo:
        $ref: '#/definitions/cardTransactionInfo'
  issuerId:
    maxLength: 10
    minLength: 10
    type: string
    description: Unique Identifier of Issuer<br/>
  cardId:
    maxLength: 64
    minLength: 1
    type: string
    description: Identifier of the funding card
  tokenId:
    maxLength: 48
    minLength: 1
    type: string
    description: Identifier of the token
  transactionType:
    type: string
    enum:
      - PURCHASE
      - REFUND
    minLength: 1
    description: Transaction type
  transactionResult:
    type: string
    enum:
      - APPROVED
      - PENDING
      - REFUNDED
      - DECLINED
    description: Transaction result status.
  transactionResultReason:
    type: number
    description: Transaction result status reason. Provided if the result is "DECLINED"
  totalAmount:
    type: number
    description: |
      Transaction amount
      Conditional to the type of transaction
  currency:
    type: string
    maxLength: 3
    minLength: 1
    description: ISO 4217 currency format numeric code (e.g. 978)
  merchant:
    type: string
    maxLength: 32
    minLength: 1
    description: |
      The merchant name.

      It is also referred as the card acceptor name.

      This parameter is mandatory for ApplePay.
  rawMerchantName:
    type: string
    maxLength: 32
    minLength: 1
    description: |-
      This field should contain the original L1 value of the merchant, as seen on a customer’s bank statement.

      It is also referred as the card acceptor identification code.

      This parameter is mandatory for ApplePay.
  merchantCity:
    type: string
    maxLength: 128
    minLength: 1
    description: Merchant Address - city
  merchantZip:
    type: string
    maxLength: 10
    minLength: 1
    description: Merchant Address -zip code
  merchantCountryCode:
    type: string
    maxLength: 2
    minLength: 2
    description: ISO 3166 Alpha 2 format
  industryCategory:
    type: string
    maxLength: 16
    minLength: 1
    description: Used to describe what type of category the merchant falls into
  industryCode:
    type: string
    maxLength: 16
    minLength: 1
    description: 'The industry category should be described using the ISO 18245 code, if possible'
  transactionDate:
    type: string
    format: date-time
    description: |
      RFC3339 format.
      Date time of the transaction.

      This parameter is mandatory for ApplePay.
  tokenTransactionInfo:
    type: object
    description: Token payment transaction information.
    properties:
      transactionType:
        $ref: '#/definitions/transactionType'
      transactionResult:
        $ref: '#/definitions/transactionResult'
      transactionResultReason:
        $ref: '#/definitions/transactionResultReason'
      linkedTransactionId:
        type: string
        maxLength: 64
        description: |
          The transactionId of a previous purchase, in case of refund.<br/>Applicable to Google Pay only.
      transactionIdentifier:
        type: string
        maxLength: 64
        minLength: 1
        description: |
          The format of the transaction identifier is in the format expected by the Wallet Provider. 
          ### **Apple Pay Transaction Identifier**:
          Shall be provided as hexadecimal string
          #### In case of EMV Transaction
          - Concatenate the TOKEN DPAN, the ATC value and the ARQC
          - Compute a SHA256 over the concatenated value
          - transactionIdentifier = SHA-256 (DPAN | ATC | Application Cryptogram)
            - *DPAN is the value of tag 5A*
            - *ATC of the tag 9F36*
            - *ARQC of the tag 9F26*
          #### In case of mCommerce Transaction
          - Concatenate the TOKEN DPAN, the ATC value and the Remote Payment Cryptogram
          - Compute a SHA256 over the concatenated value
          - *transactionIdentifier = SHA-256 (DPAN | ATC | Remote Payment Cryptogram)*
          #### In case of MagStripe Transaction
          - Concatenate :
            - 16-Less Significant Byte of SHA256  of Track 1 Data
            - with 16-Less Significant Byte of the SHA-256  of Track 2 Data
            - *transactionIdentifier = 16-LSB (SHA-256 (Track 1 Data)) | 16-LSB (SHA-256 (Track 2 Data))*
              - where Track 1 Data should be encoded in ASCII without the start sentinel, end sentinel, and longitudinal redundancy check (LRC). All other special characters should be included.
              - where Track 2 Data should be encoded in 4-bit packed BCD (binary-coded decimal). Odd-length data is padded with a hex 'F' at the end.
          #### In case of QuicPay Transaction
          - *transactionIdentifier = MSB16( SHA-256( Card ID | ATC | Expiration Date)) | 16x '00'*
            - Card ID should be 8 bytes.
            - ATC should be 2 bytes.
            - Expiration Date should be a 2 byte hex representation in YYMM format.
          ### **Google Pay Transaction Identifier**:
          #### In case of iD/QP Transaction
          - Concatenate the DPAN and transactionDate
          - Compute a SHA256 over the concatenated value
          - *transactionIdentifier = SHA-256 (DPAN | transactionDate)*
          #### In case of PURE Transaction
          - *transactionIdentifier = ATC*
      totalAmount:
        $ref: '#/definitions/totalAmount'
      currency:
        $ref: '#/definitions/currency'
      merchant:
        $ref: '#/definitions/merchant'
      rawMerchantName:
        $ref: '#/definitions/rawMerchantName'
      merchantCity:
        $ref: '#/definitions/merchantCity'
      merchantZip:
        $ref: '#/definitions/merchantZip'
      merchantCountryCode:
        $ref: '#/definitions/merchantCountryCode'
      industryCategory:
        $ref: '#/definitions/industryCategory'
      industryCode:
        $ref: '#/definitions/industryCode'
      transactionDate:
        $ref: '#/definitions/transactionDate'
    required:
      - transactionType
      - transactionResult
      - currency
  cardTransactionInfo:
    type: object
    description: Card payment transaction information.
    properties:
      transactionType:
        $ref: '#/definitions/transactionType'
      transactionResult:
        $ref: '#/definitions/transactionResult'
      transactionResultReason:
        $ref: '#/definitions/transactionResultReason'
      totalAmount:
        $ref: '#/definitions/totalAmount'
      currency:
        $ref: '#/definitions/currency'
      merchant:
        $ref: '#/definitions/merchant'
      rawMerchantName:
        $ref: '#/definitions/rawMerchantName'
      merchantCity:
        $ref: '#/definitions/merchantCity'
      merchantZip:
        $ref: '#/definitions/merchantZip'
      merchantCountryCode:
        $ref: '#/definitions/merchantCountryCode'
      industryCategory:
        $ref: '#/definitions/industryCategory'
      industryCode:
        $ref: '#/definitions/industryCode'
      transactionDate:
        $ref: '#/definitions/transactionDate'
    required:
      - transactionType
      - transactionResult
      - currency
  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|          
          |116|Unknown card|
          |119|Unknown Token|
          |911|Operation failed|
          |921|Unexpected server error|
      errorMessage:
        type: string
        description: Textual error message
tags:
  - name: Card Transactions
  - name: Token Transactions
