swagger: '2.0'
info:
  contact:
    name: ''
  description: |
    PSD2 Cryptogram Swap

    Copyright (c) 2020 Thales. All Rights Reserved
  title: PSD2 Cryptogram Swap API
  version: 1.0.0
schemes:
  - https
basePath: /tsp/psd2/v1.0
consumes:
  - application/json
produces:
  - application/json
parameters:
  x-request-id-header:
    description: Unique request identifier use to trace function calls across system
    in: header
    maxLength: 64
    minLength: 1
    name: x-request-id
    required: true
    type: string
paths:
  /transmac:
    post:
      summary: POST /transmac
      description: This method is used by TSH to request PSD2 compliant cryptogram
      operationId: transmac
      tags:
        - PSD2 Transcipher Mac
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/x-request-id-header'
        - name: body
          in: body
          description: transmac request payload
          required: true
          schema:
            $ref: '#/definitions/transmacReq'
      responses:
        '200':
          description: transmac response payload
          schema:
            $ref: '#/definitions/transmacRes'
        '400':
          description: 'Bad Request, Invalid request URI or header, or unsupported nonstandard parameter.<br/> Possible error codes are 111, 112, 119, 911, 921'
          schema:
            $ref: '#/definitions/errorRes'
        '500':
          $ref: '#/responses/500'
        '503':
          $ref: '#/responses/503'
responses:
  '500':
    description: |
      Internal Server Error
      Retry possible
  '503':
    description: |
      Service Unavailable
      Retry possible
          
definitions:
  transmacReq:
    type: object
    required:
      - cipheredCardInfo
    properties:
      cipheredCardInfo:
        $ref: '#/definitions/psd2CipheredCardInfoIn'
      publicKeyIdentifier:
        type: string
        minLength: 1
        maxLength: 32
        description: Identifier of the key used to encrypt cipheredCardInfo.<br/>Provided by TSP to Thales during onboarding.
  transmacRes:
    type: object
    required:
      - onlinePSD2PaymentCryptogram
    properties:
      onlinePSD2PaymentCryptogram:
        type: string
        minLength: 1
        maxLength: 128
        description: 'Base64 encoded PSD2 compliant cryptogram. It''s the same structure as the one provided as input but with the swapped RPC, PSD2 compliant.'
  psd2CipheredCardInfoIn:
    maxLength: 8196
    minLength: 1
    type: string
    description: |-
      TSH sends card information as 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 TSPs.
      * 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 card info contains the following information:<br/>

      |JSON field parameter name|description|MOC|Length|
      |-------|-------|-------|-------|
      |applicationPrimaryAccountNumber|The DPAN|M|Up to 19|
      |applicationExpirationDate|The token expiry date in the format YYMMDD|M|6|
      |paymentDataType|One of "3DSecure" or "EMV"|M|Up to 8|
      |onlinePaymentCryptogram|Base64 encoded non PSD2 compliant cryptogram|M|Up to 28|
      |eciIndicator|ECI indicator|O|Up to 2|
      |transactionAmount|Transaction amount as number|M|-|
      |transactionTimestamp|Timestamp of the transaction in format "YYMMDD HH:mm". Timezone is UTC|M|Up to 12|
      |currencyCode|The three-letter ISO 4217 currency code for the payment|M|3|
      |merchantIdentifier|The merchant identifier|M|Up to 64|
  errorRes:
    type: object
    description: Error Information Response
    required:
      - responseCode
    properties:
      responseCode:
        type: number
        description: |
          Error Response code to the request
          |Error code | Description| Retryable|
          |-------|-------|-------|
          |111|Missing mandatory parameter|N|
          |112|Bad parameter format|N|
          |113|Unknown issuer|N|
          |115|Unknown product|N|
          |119|Unknown Token|N|
          |163|Product not supported for mobile payment|N|
          |164|FPAN Digitization Count Exceeded|N|
          |166|Invalid FPAN|N|
          |167|Card already enrolled|N|
          |321|Operation on token already on-going|N|
          |322|Time to live of the operation expired|N|
          |431|Invalid perso data|N|
          |432|Current token state does not allow this operation|N|
          |911|Operation failed|N|
          |921|Unexpected server error|Y|
      errorMessage:
        type: string
        description: Textual error message
tags:
  - name: PSD2 Transcipher Mac
