openapi: 3.0.3
info:
  title: "Worldline RVM - Responding PSP API"
  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
servers:
  - url: "/vop"
paths:
  /v1/identifications:
    post:
      summary: Request Account Holder Information for a given account identifier.
      operationId: accountInformationRequest
      parameters:
        - name: "Authorization"
          in: "header"
          description: |
            The Bearer token fetched from the authentication server of the responding PSP.
          required: true
          schema:
            type: "string"
        - 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:
  schemas:
    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'
    
    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:
                    description: Legal Entity Identifier.
                    allOf:
                      - $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
    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
    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:
          description: Unique and unambiguous identification of an organisation.
          allOf:
            - $ref: '#/components/schemas/Max256Text'
        schemeNameCode:
          description: An entry provided by an external ISO code list.
          allOf:
            - $ref: '#/components/schemas/OrganisationIdentificationCode'
        schemeNameProprietary:
          description: A scheme name defined in a proprietary way.
          allOf:
            - $ref: '#/components/schemas/Max35Text'
        issuer:
          description: Issuer of the identification.
          allOf:
            - $ref: '#/components/schemas/Max35Text'
      required:
        - identification
    VerificationOfPayeeResponse:
      description: | 
        Separation of the two kinds of responses in different structures allows constraints on code identification results and name inclusion.
        Mutual exclusion is verified by business rules executed after the json parsing.
        If the result of partyNameMatch is CMTC, then matchedName is mandatory and can only be used in this case.
      type: object
      properties:
        partyNameMatch:
          $ref: '#/components/schemas/NameMatchType'
        partyIdMatch:
          $ref: '#/components/schemas/PartyIdMatchType'
        matchedName:
          $ref: '#/components/schemas/Max140Text'
    AccountHolderInfoError:
      type: object
      properties:
        type: 
          $ref: '#/components/schemas/Max70Text'
        code:
          description: An entry provided by an external ISO code list.
          allOf:
            - $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
    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
    IBANType: 
      type: string
      pattern: '^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$'
    BICType: 
      type: string
      pattern: '^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$'
      example: 'ABCDBEBBFIM'
    LEIType: 
      type: string
      pattern: '^[A-Z0-9]{18}[0-9]{2}$'
      description: "Code LEI (Legal Entity Identifier) ISO 17442"
      example: '549300DTUYXVMJXZNY75'
    NameMatchType:
      type: string
      enum: [MTCH, CMTC, NMTC, NOAP]
    PartyIdMatchType:
      type: string
      enum: [MTCH, NMTC, NOAP]  
    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'
    MessageCode:
      type: string
      enum: [FORMAT_ERROR, CLIENT_INVALID, CLIENT_INCONSISTENT, TIMESTAMP_INVALID]