openapi: 3.0.4
info:
  title: VoP - Responding PSP
  description: |
    Technical specification for the VOP Application Programming Interface, exposed by Responding PSPs for Worldline to answer VoP requests on their behalf as RVM in the scheme.
  version: 1.0.0-RC
security:
  - oAuthSSO: [ VOP ]
paths:
  /v1/identifications:
    post:
      tags:
        - Responding PSP
      summary: Request the Account Holder Information for a given account identifier.
      description: |-
        This endpoint is intended to be exposed by the responding PSP and called by the intermediate PSP / RVM role in the Verification of Payee process.<br>
        The endpoint answers a request for account holder information in real time.
      operationId: accountInformationRequest
      parameters:
        - name: X-Request-ID
          description: The Requesting PSP's reference number of the VOP Request
          in: header
          schema:
            type: string
            format: uuid
          required: true
        - name: X-Request-Timestamp
          description: |
            Forwarded timestamp of the VOP Request in ISO 8601 format, either UTC (YYYY-MM-DDThh:mm:ss.sssZ) or local time with UTC offset (YYYY-MM-DDThh:mm:ss.sss+/-hh:mm), milliseconds included.
          in: header
          schema:
            type: string
            format: date-time
          example: '2024-08-12T15:19:21.123Z'
          required: true
      requestBody:
        description: "Account Holder Information Request."
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountHolderInfoRequest'
      responses:
        '200':
          description: |
            OK
            The result of the account holder information request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountHolderInfoResponse'
        '400':
          description: |
            Bad request
            The result code is given, if there is anything wrong with the request sent by the client, i.e. missing fields or invalid information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountHolderInfoError'
        '401':
          description: |
            Unauthorized
            The result code is given, if the client could not be authorized, i.e. the access token header could not be verified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountHolderInfoError'
        '404':
          description: |
            Not found.
            The result code is given, if the requested account information could not be retrieved by the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountHolderInfoError'
        '500':
          description: |
            Internal Server error
            The result code is given, if there was a problem on server side handling the request. The response body might contain additional information. Try the request again later, if the problem persists notify your contact person of the problem.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountHolderInfoError'

components:
  securitySchemes:
    oAuthSSO:
      type: oauth2
      description: This API uses OAuth 2 with the client credential grant flow. [More info](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow). The Authorization header for each request must be filled with an access token collected from the token url.
      flows:
        clientCredentials:
          tokenUrl: https://localhost:48443/auth/realms/merchant-clients/protocol/openid-connect/token
          scopes:
            VOP: Scope for accessing the Verification of Payee ressources
  schemas:
    AccountHolderInfoError:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/Max70Text'
        code:
          $ref: '#/components/schemas/MessageCode'
        title:
          $ref: '#/components/schemas/Max70Text'
        status:
          type: integer
          enum: [ 400,401,500 ]
        detail:
          $ref: '#/components/schemas/Max500Text'
        instance:
          $ref: '#/components/schemas/Max256Text'
      required:
        - type
        - code

    AccountHolderInfoRequest:
      type: object
      additionalProperties: false
      required:
        - partyAgent
        - partyAccount
        - requestingAgent
      properties:
        partyAgent:
          $ref: '#/components/schemas/AgentType'
        partyAccount:
          $ref: '#/components/schemas/AccountType'
        requestingAgent:
          $ref: '#/components/schemas/AgentType'

    AccountHolderInfoResponse:
      type: object
      additionalProperties: false
      required:
        - payee
      properties:
        payee:
          $ref: '#/components/schemas/PartyType'

    AccountType:
      type: object
      properties:
        iban:
          $ref: '#/components/schemas/IBANType'
      required:
        - iban

    AgentType:
      type: object
      properties:
        financialInstitutionId:
          type: object
          properties:
            bicfi:
              $ref: '#/components/schemas/BICType'
          required:
            - bicfi
      required:
        - financialInstitutionId

    BICType:
      type: string
      pattern: '^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$'
      example: 'ABCDBEBBFIM'

    GenericOrganisationIdentification:
      description: |
        Usage Rule: the use of either ‘schemeNameCode’ or ‘schemeNameProprietary’ is mandatory when the ‘identification code’ is used.
        Mutual exclusion is verified by business rules executed after the json parsing.
      type: object
      properties:
        identification:
          $ref: '#/components/schemas/Max256Text'
        schemeNameCode:
          $ref: '#/components/schemas/OrganisationIdentificationCode'
        schemeNameProprietary:
          $ref: '#/components/schemas/Max35Text'
        issuer:
          $ref: '#/components/schemas/Max35Text'
      required:
        - identification

    IBANType:
      type: string
      pattern: '^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$'

    LEIType:
      type: string
      pattern: '^[A-Z0-9]{18}[0-9]{2}$'
      description: "Code LEI (Legal Entity Identifier) ISO 17442"
      example: '549300DTUYXVMJXZNY75'

    Max35Text:
      type: string
      minLength: 0
      maxLength: 35

    Max70Text:
      type: string
      minLength: 0
      maxLength: 70

    Max140Text:
      type: string
      minLength: 0
      maxLength: 140

    Max256Text:
      type: string
      minLength: 0
      maxLength: 256

    Max500Text:
      type: string
      minLength: 0
      maxLength: 500

    MessageCode:
      type: string
      enum: [ FORMAT_ERROR, CLIENT_INVALID, CLIENT_INCONSISTENT, TIMESTAMP_INVALID ]

    OrganisationIdentificationCode:
      description: Specifies the external organisation identification scheme name code (maximum 4 characters) as defined in an external list (iso20022.org).
      type: string
      enum: [ BANK, CBID, CHID, CINC, COID, CUST, DUNS, EMPL, GS1G, SREN, SRET, TXID, BDID, BOID ]
      example: 'BOID'

    PartyType:
      description: |
        Separation of the two kinds of identification into distinct structures ensures that the two sets of attributes are mutually exclusive.
        Mutual exclusion is verified by business rules executed after the json parsing.
      type: object
      required:
        - name
      properties:
        name:
          type: array
          items:
            $ref: '#/components/schemas/Max140Text'
        identification:
          type: object
          properties:
            organisationId:
              type: object
              properties:
                lei:
                  $ref: '#/components/schemas/LEIType'
                anyBIC:
                  $ref: '#/components/schemas/BICType'
                others:
                  description: |
                    Unique identification of an organisation, as assigned by an institution, using an identification scheme.
                    Usage Rule: only one entry to be used.
                  type: array
                  items:
                    $ref: '#/components/schemas/GenericOrganisationIdentification'
          required:
            - organisationId