openapi: 3.1.0
info:
  title: Referential WS Server
  description: |
    REST API used for public referential operations.
    
    Different versions exist for this API, identified by the version number included in the URI.
    This specification describe the version **2023R3-1.0**.
  version: "25R1.0"
paths:
  /2023R3-1.0/public/copyCard/{requestId}:
    post:
      description: |
        This function is used for copying credential data from one card to another.
      operationId: copyCard
      parameters:
        - name: Api-Key
          in: header
          required: true
          schema:
            type: string
        - name: requestId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            examples:
              - "38400000-8cf0-11bd-b23e-10b96e4ef00e"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicCopyCardRequest'
      responses:
        "200":
          description: Card copied successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSearchCardResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "520":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
  /2023R3-1.0/public/searchCard/{requestId}:
    post:
      description: |
        Search card by pan, token pan and expiry date.
      operationId: searchCard
      parameters:
        - name: Api-Key
          in: header
          required: true
          schema:
            type: string
        - name: requestId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            examples:
              - "38400000-8cf0-11bd-b23e-10b96e4ef00e"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicSearchCardRequest'
      responses:
        "200":
          description: Default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSearchCardResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "520":
          description: Unknown Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
  /2023R3-1.0/public/searchUserCredentials/{requestId}:
    post:
      description: |
        Search user credentials by card holder ID.
      operationId: searchUserCredentials
      parameters:
        - name: Api-Key
          in: header
          required: true
          schema:
            type: string
        - name: requestId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            examples:
              - "38400000-8cf0-11bd-b23e-10b96e4ef00e"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicSearchUserCredentialsRequest'
      responses:
        "200":
          description: Returns all the valid cards and associated credentials linked to a user.
            If no credential is active/present, the card will not be listed in the response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSearchUserCredentialsResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "520":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
  /2023R3-1.0/public/searchVirtualCard/{requestId}:
    post:
      description: Get Virtual Card.
      operationId: searchVirtualCard
      parameters:
        - name: Api-Key
          in: header
          required: true
          schema:
            type: string
        - name: requestId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            examples:
              - "38400000-8cf0-11bd-b23e-10b96e4ef00e"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/searchVirtualCardRequest'
      responses:
        "200":
          description: Virtual card retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/searchVirtualCardResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "520":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
  /2023R3-1.0/public/updateCardWithCredentials/{requestId}:
    post:
      description: |
        This function will be used to create or update a card with its credentials.
        In case of request for more than one card, any error on one card will dismiss
        the update / creation of all the cards.
      operationId: updateCardWithCredentials
      parameters:
        - name: Api-Key
          in: header
          required: true
          schema:
            type: string
        - name: requestId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            examples:
              - "38400000-8cf0-11bd-b23e-10b96e4ef00e"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCardWithCredentialsRequest'
      responses:
        "200":
          description: Card updated (only one card in the request)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateCardWithCredentialsResponse'
        "201":
          description: Card created (only one card in the request)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateCardWithCredentialsResponse'
        "202":
          description: Multiple cards created / updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateCardWithCredentialsResponse'
        "208":
          description: Card has been updated after the effective date provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "520":
          description: Unknown Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
  /2023R3-1.0/public/updateUserCredentials/{requestId}:
    post:
      description: |
        This method is used to update credentials of all cards for specified user.
        In case of request for more than one card, any error on one card will dismiss 
        the update / creation for other cards.
      operationId: updateUserCredentials
      parameters:
        - name: Api-Key
          in: header
          required: true
          schema:
            type: string
        - name: requestId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            examples:
              - "38400000-8cf0-11bd-b23e-10b96e4ef00e"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateUserCredentialsRequest'
      responses:
        "200":
          description: User credentials are updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/updateUserCredentialsResponse'
        "208":
          description: Card has been updated after the effective date provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "520":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
  /2023R3-1.0/public/virtualCard/{requestId}:
    put:
      description: Update an existing Virtual Card.
      operationId: updateVirtualCard
      parameters:
        - name: Api-Key
          in: header
          required: true
          schema:
            type: string
        - name: requestId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            examples:
              - "38400000-8cf0-11bd-b23e-10b96e4ef00e"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateVirtualCardRequest'
      responses:
        "204":
          description: Virtual Pan successfully updated
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "520":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
    post:
      description: |
        Create Virtual Card, based on a real PAN.
        
        Assumptions:
        - Virtual PAN (vPan) must be a valid PAN number (13-19 c.) with correct luhn key;
        - Expiry date can be handled for vPAN;
        - A deleteTime is mandatory for each virtual card;
        - A PAN can have multiple vPAN;
        - A vPAN must be linked to one and only one existing and active PAN.
        
        As it was already mentioned, each virtual card is associated with a real card.
        But each real card should not have more than 100 active virtual cards connected to it.
        
        Depending on the bank, the capability to retrieve the real PAN differs.
        There are banks which are configured to have external card repository, which means that 
        the real PAN remains unknown in the HUB database until the first transaction is done.
        For such Banks, a virtual PAN could be created for an unknown PAN in HUB’s database.
        Both cards, physical card (PAN) and virtual card (vPAN) will be created in one step
        based on the same request. Here is a table resuming the main use cases:
        | Card repository | PAN exists and is retrieved | Actions |
        | --- | --- | --- |
        | External | Yes | <ul><li>Create a vPAN which will be associated with already created real card PAN</li></ul> |
        | External | No | <ul><li>Create real card with PAN</li><li>Set status of real card equal to "ACTIVE"</li> <li>Do not apply any credentials to real card</li> <li>Create virtual card with vPAN and link it to newly created real card</li></ul> |
        | Hub database | Yes | <ul><li>Create a vPAN which will be associated with already created real card PAN</ul></li> |
        | Hub database | No | <ul><li>Throw an error notification with a `404030000` error code</ul></li> |
        
        Note: data names prefixed by "v" are related to virtual cards.
      operationId: createVirtualCard
      parameters:
        - name: Api-Key
          in: header
          required: true
          schema:
            type: string
        - name: requestId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            examples:
              - "38400000-8cf0-11bd-b23e-10b96e4ef00e"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVirtualCardRequest'
      responses:
        "204":
          description: Virtual Pan successfully created
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        "520":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContext'
components:
  schemas:
    CardDtoUpdateCredentials:
      required:
        - expiry
        - id
        - principal
      type: object
      properties:
        cardHolderId:
          type: string
          minLength: 8
          maxLength: 36
          format: ^[a-zA-Z0-9\-]{8,36}$
          deprecated: true
        cardId:
          type: string
          description: Card identifier.
          format: String of 2 to 36 characters
          examples:
            - "302fe46b-c234-4386-b034-8227e073cfd9"
        expiry:
          $ref: '#/components/schemas/CipherableTypedDataExpiryType'
        id:
          type: string
          description: Incremental ID, from 1 to 5. Always "1" when only one card.
          format: String of 1 character
          examples:
            - "1"
        label:
          type: string
          description: Card label It can be filled with the ACS profilset to switch
            the card to a dedicated profilset.
          format: String of 1 to 32 characters
        principal:
          allOf:
            - $ref: '#/components/schemas/CipherableTypedDataCipherablePrincipalType'
            - properties:
                type:
                  enum:
                    - pan
                    - encryptedPan
                    - tokenPan
                    - cardId
      description: List of the cards
    CardResponse:
      type: object
      required:
        - cardHolderId
        - id
        - tokenPan
        - cardId
      properties:
        cardHolderId:
          type: string
          minLength: 8
          maxLength: 36
          format: ^[a-zA-Z0-9\-]{8,36}$
          examples:
            - "71b2bb27-3aa8-47ee-b594-d52f21f38ea7"
        cardId:
          type: string
          minLength: 8
          maxLength: 36
          format: ^[a-zA-Z0-9\-]{2,36}$
          examples:
            - "30a93d15-c8f0-4bee-848e-b029c3e6c8e1"
        id:
          type: string
          description: Card identifier
          examples:
            - "1"
        language:
          type: string
          minLength: 2
          maxLength: 2
          description: Language of the customer, as defined by the ISO 639-1 standard
          examples:
            - "fr"
        tokenPan:
          type: string
    CipherableTypedDataCipherablePrincipalType:
      type: object
      properties:
        keyTag:
          type: string
          minLength: 2
          maxLength: 2
          description: keytag used in case of encrypted principal
          examples:
            - "01"
        type:
          type: string
          description: Ciphered principal
          examples:
            - "pan"
        value:
          type: string
          minLength: 1
          maxLength: 255
          examples:
            - "4539382046594879"
      description: Principal
    CipherableTypedDataCredentialsType:
      type: object
      properties:
        keyTag:
          type: string
          minLength: 2
          maxLength: 2
          description: keytag used in case of encrypted credentials
          examples:
            - "01"
        type:
          type: string
          oneOf:
            - enum:
              - plain
              - encrypted
            - enum:
              - credentials
              - encryptedCredentials
              deprecated: true
        value:
          type: string
          description: Plain or encrypted string representing a map of credentials
            where the key corresponds to the credential type and the value to a list 
            of map containing the credential type associated to its actual value. 
            Depending of the credential type, the inner map can also require 
            additional data like the pattern (for a birthdate) or the algorithm 
            (for a hashed password).
          examples:
            - "{\"METHOD:SMS\":[{\"sms\":\"+491741234567\"}],\"METHOD:DDN\":[{\"ddn\":\"19810803\",\"ddnPattern\":\"AAAAMMJJ\"}]}"
      description: |
        Credentials. This field cannot be used at the same time as `credentialList`.
        Prefer using `credentialList` instead.
    CipherableTypedDataExpiryType:
      type: object
      properties:
        keyTag:
          type: string
          minLength: 2
          maxLength: 2
          description: keytag used in case of encrypted expiry date
          examples:
            - "01"
        type:
          type: string
          description: Expiry date
          oneOf:
            - enum:
              - plain
              - encrypted
            - enum:
              - expiry
              - encryptedExpiry
              deprecated: true
        value:
          type: string
          format: yyyy-MM (plain)
      description: Ciphered data
      examples:
        - {
            "type": "plain",
            "value": "2023-10"
          }
    CreateVirtualCardRequest:
      required:
        - issuerCode
        - principal
        - service
        - subIssuerCode
        - vDeletedTime
        - vExpiryDate
        - vPrincipal
      type: object
      properties:
        inializationVector:
          type: string
          enum:
            - true
            - false
          description: Usage of initialization vector for encryption (`false` by default).
            If `true`, the `requestId` without dashes ('-') is used as initialization vector.
        issuerCode:
          minLength: 5
          maxLength: 5
          type: string
          description: Issuer code
          examples:
            - "66666"
        principal:
          allOf:
            - $ref: '#/components/schemas/CipherableTypedDataCipherablePrincipalType'
            - properties:
                type:
                  enum:
                    - pan
                    - encryptedPan
                    - tokenPan
                    - cardId
        service:
          minLength: 1
          maxLength: 255
          type: string
          description: Calling service
          examples:
            - "ACS_U9F"
        sessionId:
          type: string
          description: Session ID
        subIssuerCode:
          minLength: 5
          maxLength: 5
          type: string
          description: sub issuer code
          examples:
            - "66666"
        vDeletedTime:
          type: string
          format: yyyy-MM-dd'T'HH:mm:ss
          description: Date of end of validity of the virtual card. 
            After this date, the virtual card is logically deleted and no more usable.
            Must be in future.
          examples:
            - "2025-12-03T10:15:30"
        vExpiryDate:
          $ref: '#/components/schemas/CipherableTypedDataExpiryType'
        vPrincipal:
          allOf:
            - $ref: '#/components/schemas/CipherableTypedDataCipherablePrincipalType'
            - properties:
                type:
                  enum:
                    - pan
                    - encryptedPan
      description: Create Virtual Card Request resource representation
    Credential:
      required:
        - type
        - value
      type: object
      properties:
        algorithm:
          type: string
          description: Credential algorithm, only for PWD means
          examples:
            - "SHA-256"
        pattern:
          type: string
          description: Credential pattern, only for DDN means
          examples:
            - "AAAAMMJJ"
        type:
          type: string
          description: Credential type
          enum:
            - PWD
            - DDN
            - SSN
            - PAM
            - TOKEN
            - TA
            - EMAIL
            - SMS
            - IVR
            - CCP
            - SVI
            - PHONE
            - OTRC
            - USERCODE
            - OPENID
          examples:
            - "IVR"
        value:
          type: string
          minLength: 1
          maxLength: 255
          description: Credential value
          examples:
            - "+37477445464"
      description: Credential DTO resource representation
    PublicCopyCardRequest:
      required:
        - issuerCode
        - newCardStatus
        - newDeletedTime
        - newExpiryDate
        - newPan
        - oldPan
        - service
        - subIssuerCode
      type: object
      properties:
        cardHolderId:
          minLength: 8
          maxLength: 36
          format: ^[a-zA-Z0-9\-]{8,36}$
          type: string
          description: Cardholder ID
          examples:
            - "302fe46b-c234-4386-b034-8227e073cfd9"
        inializationVector:
          type: string
          enum:
            - true
            - false
          description: Usage of initialization vector for encryption (`false` by default).
            If `true`, the `requestId` without dashes ('-') is used as initialization vector.
        issuerCode:
          minLength: 5
          maxLength: 5
          type: string
          description: Issuer code
          examples:
            - "66666"
        newCardId:
          minLength: 2
          maxLength: 36
          type: string
          description: Copy card request new card Id.
        newCardStatus:
          type: string
          description: New card status.
          enum:
            - ACTIVE
            - INACTIVE
            - DELETED
        newDeletedTime:
          type: string
          description: Copy card request new deleted time. Date of end of life in
            ACS of the new card
          format: yyyy-MM-dd'T'HH:mm:ss
          examples:
            - "2025-12-03T10:15:30"
        newExpiryDate:
          $ref: '#/components/schemas/CipherableTypedDataExpiryType'
        newPan:
          allOf:
            - $ref: '#/components/schemas/CipherableTypedDataCipherablePrincipalType'
            - properties:
                type:
                  enum:
                    - pan
                    - encryptedPan
                    - tokenPan
                    - cardId
        oldCardStatus:
          type: string
          description: Old card status. Updated status of the old card after the request
            (if not provided the status will be unchanged).
          enum:
            - ACTIVE
            - INACTIVE
            - DELETED
        oldDeletedTime:
          type: string
          description: Copy card request old deleted time. Date of blocking card on
            ACS3.0 (if not provided the date will be unchanged)
          format: date-time
        oldPan:
          allOf:
            - $ref: '#/components/schemas/CipherableTypedDataCipherablePrincipalType'
            - properties:
                type:
                  enum:
                    - pan
                    - encryptedPan
                    - tokenPan
                    - cardId
        service:
          minLength: 1
          maxLength: 255
          type: string
          description: Calling service
          examples:
            - "ACS_U9F"
        subIssuerCode:
          minLength: 5
          maxLength: 5
          type: string
          description: sub issuer code
          examples:
            - "66666"
      description: PublicCopyCardRequest DTO resource representation
    PublicSearchCardRequest:
      required:
        - issuerCode
        - principal
        - service
        - subIssuerCode
      type: object
      properties:
        cardHolderId:
          minLength: 8
          maxLength: 36
          format: ^[a-zA-Z0-9\-]{8,36}$
          type: string
          description: Cardholder ID
          examples:
            - "302fe46b-c234-4386-b034-8227e073cfd9"
        expiry:
          $ref: '#/components/schemas/CipherableTypedDataExpiryType'
        inializationVector:
          type: string
          enum:
            - true
            - false
          description: Usage of initialization vector for encryption (`false` by default).
            If `true`, the `requestId` without dashes ('-') is used as initialization vector.
        issuerCode:
          minLength: 5
          maxLength: 5
          type: string
          description: Issuer code
          examples:
            - "66666"
        principal:
          allOf:
            - $ref: '#/components/schemas/CipherableTypedDataCipherablePrincipalType'
            - properties:
                type:
                  enum:
                    - pan
                    - encryptedPan
                    - tokenPan
                    - cardId
        requestId:
          type: string
          description: Request ID
          format: String
          examples:
            - "38400000-8cf0-11bd-b23e-10b96e4ef00e"
        service:
          minLength: 1
          maxLength: 255
          type: string
          description: Calling service
          examples:
            - "ACS_U9F"
        subIssuerCode:
          minLength: 5
          maxLength: 5
          type: string
          description: sub issuer code
          examples:
            - "66666"
      description: PublicSearchCardRequest DTO resource representation
    PublicSearchCardResponse:
      type: object
      required:
        - id
        - createdTime
        - token
        - cardHolderId
        - status
        - expiryDate
      properties:
        cardHolderId:
          type: string
          minLength: 8
          maxLength: 36
          format: ^[a-zA-Z0-9\-]{8,36}$
          description: Cardholder ID
          examples:
            - "71b2bb27-3aa8-47ee-b594-d52f21f38ea7"
        cardId:
          type: string
          minLength: 2
          maxLength: 36
          format: ^[a-zA-Z0-9\-]{2,36}$
          description: Card identifier
          examples:
            - "30a93d15-c8f0-4bee-848e-b029c3e6c8e1"
        createdTime:
          type: string
          format: yyyy-MM-dd'T'HH:mm:ss
          description: UTC date time of the creation
          examples:
            - "2022-12-01T11:43:59"
        credentials:
          $ref: '#/components/schemas/CipherableTypedDataCredentialsType'
        credentialList:
          type: array
          description: Credentials.
          items:
            $ref: '#/components/schemas/Credential'
        data:
          type: string
          description: Card data. Serialized JSON for future usage.
        deletedTime:
          type: string
          format: yyyy-MM-dd'T'HH:mm:ss
          description: UTC date time of the deletion
          examples:
            - "2022-11-11T11:11:11"
        expiryDate:
          type: string
          format: yyyy-MM
          description: Expiry date of the card
          examples:
            - "2025-12"
        firstName:
          type: string
          minLength: 1
          maxLength: 50
          description: First name
          examples:
            - "John"
        id:
          type: string
          format: uuid
          description: Card ID
        label:
          type: string
          description: Card label. It can be filled with the ACS profilset 
            to switch the card to a dedicated profilset.
        language:
          type: string
          minLength: 2
          maxLength: 2
          description: Language of the customer, as defined by the ISO 639-1 standard
          examples:
            - "fr"
        lastName:
          type: string
          minLength: 1
          maxLength: 50
          description: Last name
          examples:
            - "Doe"
        status:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
            - DELETED
          description: Status of the card
        token:
          type: string
          description: Token PAN
          examples:
            - "g0096110c22a10d0"
        updatedTime:
          type: string
          format: yyyy-MM-dd'T'HH:mm:ss
          description: UTC date time of the update
          examples:
            - "2023-03-10T13:28:59"
      description: PublicSearchCardResponse DTO resource representation
    PublicSearchUserCredentialsRequest:
      required:
        - issuerCode
        - cardHolderId
        - service
        - subIssuerCode
      type: object
      properties:
        cardHolderId:
          minLength: 8
          maxLength: 36
          format: ^[a-zA-Z0-9\-]{8,36}$
          type: string
          description: Cardholder ID
          examples:
            - "302fe46b-c234-4386-b034-8227e073cfd9"
        inializationVector:
          type: string
          enum:
            - true
            - false
          description: Usage of initialization vector for encryption (`false` by default).
            If `true`, the `requestId` without dashes ('-') is used as initialization vector.
        issuerCode:
          minLength: 5
          maxLength: 5
          type: string
          description: Issuer code
          examples:
            - "66666"
        requestId:
          type: string
          description: Request ID
          format: String
        service:
          minLength: 1
          maxLength: 255
          type: string
          description: Calling service
          examples:
            - "ACS_U9F"
        subIssuerCode:
          minLength: 5
          maxLength: 5
          type: string
          description: sub issuer code
          examples:
            - "66666"
        principal:
          allOf:
            - $ref: '#/components/schemas/CipherableTypedDataCipherablePrincipalType'
            - properties:
                type:
                  enum:
                    - pan
                    - encryptedPan
                    - tokenPan
                    - cardId
      description: PublicSearchUserCredentialsRequest DTO resource representation
    PublicSearchUserCredentialsResponse:
      type: object
      required:
          - cardHolderId
          - cardResponses
      properties:
        cardHolderId:
          type: string
          minLength: 8
          maxLength: 36
          format: ^[a-zA-Z0-9\-]{8,36}$
          description: Cardholder ID
          examples:
            - "71b2bb27-3aa8-47ee-b594-d52f21f38ea7"
        cardResponses:
          type: array
          items:
            $ref: '#/components/schemas/UserCredentialsCardResponse'
        firstName:
          type: string
          description: cardholder's first name
          examples:
            - "John"
        language:
          type: string
          minLength: 2
          maxLength: 2
          description: Language of the customer, as defined by the ISO 639-1 standard
          examples:
            - "fr"
        lastName:
          type: string
          description: cardholder's last name
          examples:
            - "Doe"
      description: PublicSearchUserCredentialsResponse DTO resource representation
    searchVirtualCardRequest:
      required:
        - issuerCode
        - service
        - subIssuerCode
        - vPrincipal
      type: object
      properties:
        inializationVector:
          type: string
          enum:
            - true
            - false
          description: Usage of initialization vector for encryption (`false` by default).
            If `true`, the `requestId` without dashes ('-') is used as initialization vector.
        issuerCode:
          minLength: 5
          maxLength: 5
          type: string
          description: Issuer code
          examples:
            - "66666"
        service:
          minLength: 1
          maxLength: 255
          type: string
          description: Calling service
          examples:
            - "ACS_U9F"
        subIssuerCode:
          minLength: 5
          maxLength: 5
          type: string
          description: sub issuer code
          examples:
            - "66666"
        vPrincipal:
          allOf:
            - $ref: '#/components/schemas/CipherableTypedDataCipherablePrincipalType'
            - properties:
                type:
                  enum:
                    - pan
                    - encryptedPan
      description: Read Virtual Card Request resource representation
    searchVirtualCardResponse:
      type: object
      required:
        - createdTime
        - principal
        - vDeletedTime
        - vPrincipal
      properties:
        createdTime:
          type: string
          format: yyyy-MM-dd'T'HH:mm:ss
          description: Virtual card created time
          examples:
            - "2022-12-01T11:43:59"
        principal:
          allOf:
            - $ref: '#/components/schemas/CipherableTypedDataCipherablePrincipalType'
            - properties:
                type:
                  enum:
                    - pan
                    - encryptedPan
                    - tokenPan
        updatedTime:
          type: string
          format: yyyy-MM-dd'T'HH:mm:ss
          description: Virtual card updated time
          examples:
            - "2023-03-10T13:28:59"
        vDeletedTime:
          type: string
          format: yyyy-MM-dd'T'HH:mm:ss
          description: Virtual Card deleted time
          examples:
            - "2025-12-03T10:15:30"
        vExpiryDate:
          $ref: '#/components/schemas/CipherableTypedDataExpiryType'
        vPrincipal:
          allOf:
            - $ref: '#/components/schemas/CipherableTypedDataCipherablePrincipalType'
            - properties:
                type:
                  enum:
                    - pan
                    - encryptedPan
                    - tokenPan
      description: searchVirtualCardResponse resource representation
    UpdateCardWithCredentialsRequest:
      required:
        - cards
        - issuerCode
        - service
        - subIssuerCode
      type: object
      properties:
        cardHolderId:
          minLength: 8
          maxLength: 36
          format: ^[a-zA-Z0-9\-]{8,36}$
          type: string
          description: Cardholder ID
          examples:
            - "302fe46b-c234-4386-b034-8227e073cfd9"
        cards:
          type: array
          description: List of the cards
          items:
            $ref: '#/components/schemas/CardDtoUpdateCredentials'
        credentialList:
          type: array
          description: |
            List of credentials of the card, used in 23R2 or higher.
            This field cannot be used at the same time as `credentials`.
            Prefer using this field instead of `credentials`.
          items:
            $ref: '#/components/schemas/Credential'
        credentials:
          $ref: '#/components/schemas/CipherableTypedDataCredentialsType'
        credentialsUpdateMode:
          type: string
          description: |
            Specify what to do with AuthenticationData:
              - `UPDATE` (default value): if AuthenticationData is provided for an
              authentication mean, replace existing values (if any) with provided one. 
              Other authentication means (not provided in file) will be kept.
              - `DELETE_AND_CREATE`: existing AuthenticationData (for all authentication
              means) will be deleted and replaced by provided one. If the card does not
              exists yet, result will be the same as `UPDATE`.
              - DELETE: delete all credentials of one type linked to a card. If credential
              type (means like TA, SMS…) that are provided for a given card does not have
              any data associated, it will be skipped. if AuthenticationData is provided for
              an authentication mean, remove all existing values (if any) for provided one.
          enum:
            - UPDATE
            - DELETE_AND_CREATE
            - DELETE
        deletedTime:
          type: string
          description: Deletion date of the card. Once this date is expired, 
            the card is no more usable on 3DS.
          format: yyyy-MM-dd'T'HH:mm:ss
          examples:
            - "2022-11-11T11:11:11"
        effectiveUpdateDate:
          type: string
          format: yyyy-MM-dd'T'HH:mm:ss
          description: Effective update date of the card which is 
            compared with the card / credential / user updated date.
          examples:
            - "2024-01-16T13:23:55"
        expiry:
          allOf:
            - $ref: '#/components/schemas/CipherableTypedDataExpiryType'
            - deprecated: true
        firstName:
          minLength: 1
          maxLength: 64
          type: string
          description: cardholder's first name
          examples:
            - "John"
        inializationVector:
          type: string
          enum:
            - true
            - false
          description: Usage of initialization vector for encryption (`false` by default).
            If `true`, the `requestId` without dashes ('-') is used as initialization vector.
        issuerCode:
          minLength: 5
          maxLength: 5
          type: string
          description: Issuer code
          examples:
            - "66666"
        keyTag:
          minLength: 2
          maxLength: 2
          type: string
          description: used in case of encrypted fields in credentialList
          examples:
            - "01"
        label:
          type: string
          deprecated: true
        language:
          minLength: 2
          maxLength: 2
          type: string
          description: Language of the customer, as defined by the ISO 639-1 standard
          examples:
            - "fr"
        lastName:
          minLength: 1
          maxLength: 64
          type: string
          description: cardholder's last name
          examples:
            - "Doe"
        principal:
          allOf:
            - $ref: '#/components/schemas/CipherableTypedDataCipherablePrincipalType'
            - deprecated: true
            - properties:
                type:
                  enum:
                    - pan
                    - encryptedPan
                    - tokenPan
                    - cardId
        requestId:
          type: string
          description: Request ID
          format: String
        service:
          minLength: 1
          maxLength: 255
          type: string
          description: Calling service
          examples:
            - "ACS_U9F"
        sessionId:
          type: string
          description: Session ID. Not used.
        status:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
          description: Status of the card (`ACTIVE` by default)
        subIssuerCode:
          minLength: 5
          maxLength: 5
          type: string
          description: sub issuer code
          examples:
            - "66666"
      description: UpdateCardWithCredentialsRequest DTO resource representation.
        Credentials can be provided in either _credentials_ format or in 
        _credentialList_ format, but not in both formats at the same time.
        Prefer the more simple _credentialList_ format if possible.
    UpdateCardWithCredentialsResponse:
      type: object
      properties:
        cardResponses:
          type: array
          items:
            $ref: '#/components/schemas/CardResponse'
      description: UpdateCardWithCredentialsResponse DTO resource representation
    updateUserCredentialsRequest:
      required:
        - expiry
        - issuerCode
        - principal
        - service
        - subIssuerCode
      type: object
      properties:
        cardHolderId:
          minLength: 8
          maxLength: 36
          format: ^[a-zA-Z0-9\-]{8,36}$
          type: string
          description: Cardholder ID
          examples:
            - "302fe46b-c234-4386-b034-8227e073cfd9"
        credentialList:
          type: array
          description: |
            Credentials list of the card.
            This field cannot be used at the same time as `credentials`.
            Prefer using this field instead of `credentials`.
          items:
            $ref: '#/components/schemas/Credential'
        credentials:
          $ref: '#/components/schemas/CipherableTypedDataCredentialsType'
        credentialsUpdateMode:
          type: string
          description: |
            Specify what to do with AuthenticationData:
              - `UPDATE` (default value): if AuthenticationData is provided for an
              authentication mean, replace existing values (if any) with provided one. 
              Other authentication means (not provided in file) will be kept.
              - `DELETE_AND_CREATE`: existing AuthenticationData (for all authentication
              means) will be deleted and replaced by provided one. If the card does not
              exists yet, result will be the same as `UPDATE`.
              - DELETE: delete all credentials of one type linked to a card. If credential
              type (means like TA, SMS…) that are provided for a given card does not have
              any data associated, it will be skipped. if AuthenticationData is provided for
              an authentication mean, remove all existing values (if any) for provided one.
          enum:
            - UPDATE
            - DELETE_AND_CREATE
            - DELETE
        effectiveUpdateDate:
          type: string
          format: yyyy-MM-dd'T'HH:mm:ss
          description: Effective update date of the card which is compared with the 
            card / credential / user updated date.
        expiry:
          $ref: '#/components/schemas/CipherableTypedDataExpiryType'
        firstName:
          minLength: 1
          maxLength: 64
          type: string
          description: cardholder's first name
          examples:
            - "John"
        inializationVector:
          type: string
          enum:
            - true
            - false
          description: Usage of initialization vector for encryption (`false` by default).
            If `true`, the `requestId` without dashes ('-') is used as initialization vector.
        issuerCode:
          minLength: 5
          maxLength: 5
          type: string
          description: Issuer code
          examples:
            - "66666"
        keyTag:
          minLength: 2
          maxLength: 2
          type: string
          description: Used in case of encrypted fields in credentialList
          examples:
            - "01"
        label:
          minLength: 1
          maxLength: 32
          type: string
          description: Card label It can be filled with the ACS profilset to switch
            the card to a dedicated profilset.
        language:
          minLength: 2
          maxLength: 2
          type: string
          description: Language of the customer, as defined by the ISO 639-1 standard
          examples:
            - "fr"
        lastName:
          minLength: 1
          maxLength: 64
          type: string
          description: cardholder's last name
          examples:
            - "Doe"
        service:
          minLength: 1
          maxLength: 255
          type: string
          description: Calling service
          examples:
            - "ACS_U9F"
        sessionId:
          type: string
          description: Session ID
        subIssuerCode:
          minLength: 5
          maxLength: 5
          type: string
          description: sub issuer code
          examples:
            - "66666"
      description: updateUserCredentialsRequest DTO resource representation
    updateUserCredentialsResponse:
      type: object
      properties:
        cardResponses:
          type: array
          items:
            $ref: '#/components/schemas/CardResponse'
      description: updateUserCredentialsResponse DTO resource representation
    UpdateVirtualCardRequest:
      required:
        - issuerCode
        - service
        - subIssuerCode
        - vPrincipal
        - vDeletedTime
      type: object
      properties:
        inializationVector:
          type: string
          enum:
            - true
            - false
          description: Usage of initialization vector for encryption (`false` by default).
            If `true`, the `requestId` without dashes ('-') is used as initialization vector.
        issuerCode:
          minLength: 5
          maxLength: 5
          type: string
          description: Issuer code
          examples:
            - "66666"
        service:
          minLength: 1
          maxLength: 255
          type: string
          description: Calling service
          examples:
            - "ACS_U9F"
        subIssuerCode:
          minLength: 5
          maxLength: 5
          type: string
          description: sub issuer code
          examples:
            - "66666"
        vDeletedTime:
          type: string
          description: Date of end of validity of the virtual card.
            After this date, the virtual card is logically deleted and no more usable.
          format: yyyy-MM-dd'T'HH:mm:ss
          examples:
            - "2025-12-03T10:15:30"
        vExpiryDate:
          $ref: '#/components/schemas/CipherableTypedDataExpiryType'
        vPrincipal:
          allOf:
            - $ref: '#/components/schemas/CipherableTypedDataCipherablePrincipalType'
            - properties:
                type:
                  enum:
                    - pan
                    - encryptedPan
      description: Update Virtual Card DTO resource representation
    UserCredentialsCardResponse:
      type: object
      required:
        - status
        - tokenPan
        - expiryDate
        - credentialList
      properties:
        credentialList:
          type: array
          items:
            $ref: '#/components/schemas/Credential'
        expiryDate:
          type: string
          format: yyyy-MM
          description: Expiry date of the card
          examples:
            - "2025-12"
        label:
          type: string
          description: Card label. It can be filled with the ACS profilset 
            to switch the card to a dedicated profilset.
        status:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
            - DELETED
          description: Status of the card
        tokenPan:
          type: string
          description: Token PAN
    MessageContext:
      type: object
      required:
        - errorCode
      properties:
        service:
          type: string
          description: Service name
          examples:
            - "ACS_U9F"
        issuerCode:
          type: string
          minLength: 5
          maxLength: 5
          description: Issuer code
          examples:
            - "66666"
        subIssuerCode:
          type: string
          minLength: 5
          maxLength: 5
          description: Sub-issuer code
          examples:
            - "66666"
        requestId:
          type: string
          format: uuid
          description: Request ID
        errorCode:
          type: string
          minLength: 9
          maxLength: 9
          description: |
            Here is a list of possible error codes and their meaning:

            <details>
              <summary>Click to expand</summary>

              | HTTP code | errorCode | Description |
              | --- | --- | --- |
              | 208 | 208000001 | Card has been updated after than the effective date provided |
              | 208 | 208000002 | Card's user has been updated after than the effective date provided |
              | 208 | 208000003 | Credential has been updated after the effective date provided |
              | 400 | 400010005 | Bad parameter: session.service |
              | 400 | 400010007 | Bad parameter: principal |
              | 400 | 400010008 | Bad Parameter: principal Type |
              | 400 | 400010009 | Bad parameter: principal value |
              | 400 | 400010010 | Bad parameter: issuer code |
              | 400 | 400010011 | Bad parameter: card.expiryDate |
              | 400 | 400010013 | Bad parameter: principal.keyTag |
              | 400 | 400010019 | Bad parameter: expiryDate |
              | 400 | 400010026 | Bad parameter: Key tag |
              | 400 | 400010028 | Bad parameter: Expiry type |
              | 400 | 400010030 | Bad parameter: Expiry value |
              | 400 | 400030001 | Bad parameter: cardinfo.id |
              | 400 | 400030002 | Bad Parameter: card info pan |
              | 400 | 400030003 | Invalid service |
              | 400 | 400080001 | Bad parameter: card id |
              | 400 | 400100005 | Bad parameter: Undefined Card |
              | 400 | 400100007 | Bad parameter: card status |
              | 400 | 400100009 | Bad parameter: card.pan (luhn check failed) |
              | 400 | 400100022 | Bad parameter: requestId |
              | 400 | 400200014 | Bad parameter: virtual principal type |
              | 403 | 403000000 | The provided Api-Key is invalid or expired. Unexpected Common Name in the client certificate. Please, contact WL if this error occurs |
              | 403 | 403900000 | Request blocked by our Firewall Security Policy. Could occurs in case of error on mutual authentication, incorrect URL, incorrect http header, unexpected text, request body is empty. Identifier in the message field is the error id logged in our F5 |
              | 404 | 404020001 | Mean Unavailable |
              | 404 | 404030000 | Card not found |
              | 404 | 404030003 | Issuer not found |
              | 404 | 404030007 | Virtual card not found |
              | 520 | 520000005 | Unexpected error during Json parsing. Json message format is incorrect |

            </details>
          examples:
            - "400100005"
        originVersion:
          type: string
          description: Origin version
          examples:
            - "21R2-P-05-SNAPSHOT"
        originHost:
          type: string
          description: Origin host
          examples:
            - "REFCLIENT"
        contextTemporary:
          type: object
          additionalProperties:
            type: string
          description: Context temporary
          examples:
            - {}
        principals:
          type: array
          description: Principals
          examples:
            - []
      description: Error body