openapi: 3.0.4
info:
  title: VoP - Requesting PSP
  version: 1.0.0-RC
  description: Technical specification for the VOP Application Programming Interface, amended by Worldline acting as RVM in the EPC VoP scheme. This description is valid for Worldline Requesting PSP customers, EPC VoP scheme participants will use the fully EPC spec compliant variant. Please consult the EPC documentation for this.
  contact:
    name: 'European Payment Council'
    url: 'https://www.europeanpaymentscouncil.eu/'
    email: 'contact@epc-cep.eu'
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
security:
  - oAuthSSO: [ VOP ]
paths:
  /v1/payee-verifications:
    post:
      tags:
        - Requesting PSP
      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
      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:
  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:
    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 ]

    NameMatchType:
      type: string
      enum: [ MTCH, CMTC, 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'

    PartyIdMatchType:
      type: string
      enum: [ MTCH, NMTC, NOAP ]

    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:
                  $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

    VerificationOfPayeeError:
      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

    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

    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'