openapi: 3.0.3
info:  
  title: "Worldline RVM - Requesting PSP API"
  version: 1.0.0
  description: "Technical specification for the VOP Application Programming Interface, amended by Worldline acting as RVM in the EPC VoP scheme. Based on: "
externalDocs:
  description: |
    Verification Of Payee Scheme Rulebook - EPC218-23
    Verification Of Payee Inter-PSP API Specification - EPC103-24
    EPC API Security Framework - EPC164-22
  url: https://www.europeanpaymentscouncil.eu/what-we-do/other-schemes/verification-payee
servers:
  - url: "/vop"
paths:
  /v1/payee-verifications:
    post:
      summary: Request a verification of the payee
      operationId: postVerificationOfPayeeRequests
      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: |
          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
      - name: Authorization
        in: header
        required: true
        description: The VoP scope token, obtained by presenting a valid QWAC containing a scheme adherent National Authorization Number, at the Worldline RVM SSO endpoint.
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationOfPayeeRequest'
      responses:
        '200':
          description: A verification code and the actual name if the code is CMTC
          headers:
            X-Request-ID:
              schema:
                type: string
                format: uuid
              required: true
            X-Response-Timestamp:
              schema:
                type: string
                format: date-time
              example: '2024-08-12T15:19:22.678Z'
              required: true
          content:
            application/json:
               schema:
                $ref: '#/components/schemas/VerificationOfPayeeResponse'
        '400':
          description: Malformed payload
          headers:
            X-Request-ID:
              schema:
                type: string
                format: uuid
              required: true
            X-Response-Timestamp:
              schema:
                type: string
                format: date-time
              example: '2024-08-12T15:19:22.678Z'
              required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationOfPayeeError'
        '401':
          description: Client invalid. The Requesting PSP is not correctly authorized to perform the request.  
          headers:
            X-Request-ID:
              schema:
                type: string
                format: uuid
              required: true
            X-Response-Timestamp:
              schema:
                type: string
                format: date-time
              example: '2024-08-12T15:19:22.678Z'
              required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationOfPayeeError'
        '500':
          description: Internal Server Error. This code is used whenever a technical problem occurred in the application code or application server that prevented the execution of the request.
          headers:
            X-Request-ID:
              schema:
                type: string
                format: uuid
              required: true
            X-Response-Timestamp:
              schema:
                type: string
                format: date-time
              example: '2024-08-12T15:19:22.678Z'
              required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationOfPayeeError'
components:
  schemas:
    VerificationOfPayeeRequest:
      type: object
      properties:
        party:
          $ref: '#/components/schemas/PartyType'
        partyAccount: 
          $ref: '#/components/schemas/AccountType'
        partyAgent: 
          $ref: '#/components/schemas/AgentType'
        unstructuredRemittanceInformation:
          description: | 
            Additional information about AT-C001 sent by the Requester AT-C007, 
            Usage Rule: only one entry may be used.
          type: array
          items:
            $ref: '#/components/schemas/Max140Text'
        requestingAgent: 
          $ref: '#/components/schemas/AgentType'
      required:
        - party
        - partyAccount
        - partyAgent
        - requestingAgent
    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
      properties:
          name: 
            $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'
    VerificationOfPayeeError:
      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]