openapi: 3.0.2
info:
  title: Worldline VoP - Requesting PSP API
  description: |
    The Worldline VoP API for Requesting PSPs describes the interface exposed by the Worldline VoP Hub, for PSPs that want to process a VoP request, to fulfill the role of requesting PSP in the VoP EPC ecosystem.
  version: 0.0.1 BETA
paths:
  /verifications:
    post:
      summary: Request a verification of payee
      description: |-
        This endpoint is intended to be called by the requesting PSP role in the Verification of Payee process.
        The endpoint will respond with the result of the responding PSP role in the Verification of Payee process, in real time according to the EPC rulebook scheme rules.
      operationId: verificationOfPayeeRequest
      parameters:
        - name: "Authorization"
          in: "header"
          description: |
            The Bearer token fetched from the authentication server. Contains the certificate to check the x-jws-signature in the cert claim.
          required: true
          schema:
            type: "string"
            example: "Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIi..."
        - name: "x-jws-signature"
          in: "header"
          description: |
            Detached JWS signature as per [RFC 7515](https://www.rfc-editor.org/rfc/rfc7515). In the header the following parameters are expected:
            * typ: JOSE
            * alg: The algorithm used in the signature (Recommended RS256)
            * kid: Key identifier to point to the key used. Should be 'cert' to point to the certificate that is included in bearer token.
          required: true
          schema:
            type: "string"
            example: "eyJ0eXAiOiJKT1NFIiwiYWxnIjoiUlMyNTYiLCJraWQiOiJjZXJ0In0..DBta3iEyxA2uEgGxNSZmOD1NVQmaGBc5LlNJ..."
      requestBody:
        description: "Verification of Payee Request."
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationOfPayeeRequest'
      responses:
        '200':
          description: |
            OK
            
            The result of the verification of payee request.
          headers:
            x-jws-signature:
              description: |
                Detached JWS signature as per [RFC 7515](https://www.rfc-editor.org/rfc/rfc7515).
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationOfPayeeResponse'
          
components:
  schemas:
    Payee:
      type: object
      required:
        - Account
        - Name
        - Agent
      properties:
        Agent:
          type: string
          description: |
            BIC of the Payee bank. C002 EPC Rulebook attribute.
        Account:
          $ref: '#/components/schemas/Account'
        Name:
          type: string
          description: |
            Name of the account holder as given by the requestor of the VoP request (legal or natural person). E001 EPC Rulebook attribute.
        AdditionalIdentification:
          type: array
          items:
            $ref: '#/components/schemas/AdditionalIdentifier'

    AdditionalIdentifier:
      type: object
      required:
        - CodeType
        - Code
      properties:
        CodeType:
          type: string
          description: |
            Type of the additional identification code, as defined in ISO standard XXXXX. Example : VAT, TAX... E013 EPC Rulebook attribute.
        Code:
          type: string
          description: |
            Additional identification code of the account holder as given by the requestor of the VoP request. Example : VAT number, TAX number... E005 EPC Rulebook attribute.

    Account:
      type: object
      required:
        - Identification
      properties:
        Identification:
          type: string
          description: |
            IBAN or other account number of the Payee account. C001 EPC Rulebook attribute.
        SchemeName:
          type: string
          description: |
            Name of the scheme used for the account number. For example and default : IBAN.
        AdditionalInformation:
          type: string
          description: |
            Additional information about the account known by the requestor. C007 EPC Rulebook attribute.
          # C007

    ErrorMessage:
      type: object
      required:
        - code
        - severity
        - text
      properties:
        severity:
          type: string
          enum:
            - Fatal
            - Transient
            - Logic
        code:
          type: string
        text:
          type: string
        user_message:
          type: string
        more_info:
          type: string
          format: uri

    NameMatchResult:
      type: object
      required:
        - Name
        - Match
      description: |
        The result of the name matching operation. R001 EPC Rulebook attribute.
      properties:
        Name:
          type: string
          description: |
            Name of the account holder as given by the requestor, used to produce the match result. E001 EPC Rulebook attribute.
        Match:
          $ref: '#/components/schemas/Match'
        AgentReportedName:
          type: string
          description: |
            Name of the account holder as reported by the Agent in case of CLOSE_MATCH result. R010 EPC Rulebook attribute.

    AdditionalIdentificationMatchResult:
      type: array
      description: |
        The result of the additional identification matching operation. R011 EPC Rulebook attribute.
      items:
        $ref: '#/components/schemas/AdditionalIdentifierMatchResult'

    AdditionalIdentifierMatchResult:
      type: object
      required:
        - AdditionalIdentifier
        - Match
      properties:
        AdditionalIdentifier:
          $ref: '#/components/schemas/AdditionalIdentifier'
        Match:
          $ref: '#/components/schemas/Match'

    Match:
      type: string
      enum:
        - MATCH
        - NO_MATCH
        - CLOSE_MATCH
        - MATCH_NOT_POSSIBLE
      description: |
        The result of the matching operation. The result can be one of the following:
        - MATCH: The name or additional identification code matches exactly the one reported by the responding PSP.
        - NO_MATCH: The name or additional identification code does not match the one reported by the responding PSP.
        - CLOSE_MATCH: The name is similar to the one reported by the responding PSP, but is not an exact match. Not applicable for additional identification codes.
        - MATCH_NOT_POSSIBLE: The additional identification is not supported by the responding PSP.
        - MATCH_ERROR : The responding PSP encountered an error while producing the match result.

    RequestingPsp:
      type: object
      required:
        - Agent
        - Reference
        - Timestamp
      properties:
        Agent:
          type: string
          description: |
            BIC of the Requesting PSP. D002 EPC Rulebook attribute.
        Reference:
          type: string
          description: |
            Unique reference of the request as given by the requesting PSP, which will identify the VoP request EndToEnd. T054 EPC Rulebook attribute.
        RequesterReference:
          type: string
          description: |
            Unique reference of the request as given by the requestor of the VoP request. T014 EPC Rulebook attribute.
        Timestamp:
          type: string
          description: |
            Timestamp of the request as given by the requesting PSP when posting the request. Used to measure execution time of the VoP request which must remain under 3 seconds end to end. T056 EPC Rulebook attribute.

    VerificationOfPayeeRequest:
      type: object
      description: Verification of Payee request.
      additionalProperties: false
      required:
        - Payee
        - RequestingPsp
      properties:
        Payee:
          $ref: '#/components/schemas/Payee'
          description: |
            The Payee related information subject of the VoP request.
        RequestingPsp:
          $ref: '#/components/schemas/RequestingPsp'
          description: |
            The RequestingPsp related information of the VoP request.

    UUIDv4Identifier:
      type: string
      description: |
        PLACEHOLDER | 
        Universally Unique IDentifier (UUID) version 4, as described in IETC RFC 4122 "Universally Unique IDentifier (UUID) URN Namespace".
      pattern: ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$

    VerificationOfPayeeResponse:
      type: object
      description: Verification of Payee response.
      additionalProperties: false
      required:
        - Uuid
        - RequestingPsp
        - NameMatchResult
        - RespondingPspTimestamp
      properties:
        Uuid:
          $ref: '#/components/schemas/UUIDv4Identifier'
        RequestingPsp:
          $ref: '#/components/schemas/RequestingPsp'
          description: |
            The RequestingPsp related information of the VoP request.
        NameMatchResult:
          $ref: '#/components/schemas/NameMatchResult'
          description: |
            The result of the name matching operation.
        AdditionalIdentificationMatchResult:
          $ref: '#/components/schemas/AdditionalIdentificationMatchResult'
          description: |
            The result of the additional identification matching operation.
        RespondingPspTimestamp:
          type: string
          description: |
            Timestamp of the response as given by the responding PSP when posting the response. Used to measure execution time of the VoP request which must remain under 3 seconds end to end. T061 EPC Rulebook attribute.