openapi: 3.0.2
info:
  title: Worldline VoP - Responding PSP API
  description: |
    The Worldline VoP API for Responding PSPs describes the interface used by the RVM (or WL VoP Hub) for PSPs that want to expose account holder information for the processing of VoP requests, to fulfill the role of responding PSP in the VoP EPC ecosystem.
  version: 0.0.1 BETA
tags:
  - name: "Account Holder Identification"

paths:
  /identifications:
    post:
      tags:
        - Account Holder Identification
      summary: Request the Account Holder Identification 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 creates a request for account holder information, answered in real time.
      operationId: accountInformationRequest
      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 cer 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 'cer' to point to the certificate that is included in bearer token.
          required: true
          schema:
            type: "string"
            example: "eyJ0eXAiOiJKT1NFIiwiYWxnIjoiUlMyNTYiLCJraWQiOiJjZXJ0In0..DBta3iEyxA2uEgGxNSZmOD1NVQmaGBc5LlNJ..."
      requestBody:
        description: "Account Holder Identification Request."
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountHolderInfoRequest'
      responses:
        '200':
          description: |
            OK
            The result of the account holder identification 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/AccountHolderInfoResponse'

components:
  schemas:
    Payee:
      type: object
      required:
        - Account
        - Names
      properties:
        Account:
          $ref: '#/components/schemas/Account'
        Names:
          type: array
          items:
            type: string
          description: |
            Names of the account holders as given by the responding bank of the VoP request (legal or natural person). A minimum of one name must be returned. 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 returned by the responding PSP of the VoP request. Example : VAT number, TAX number... E005 EPC Rulebook attribute.

    RequestedAdditionalIdentifiers:
      type: array
      description: |
        The list of additional identifier types provided by the requestor of the VoP request which should be returned by the Responding PSP if available.
      items:
        type: string
        description: |
          Type of the additional identification code, as defined in ISO standard XXXXX. Example : VAT, TAX... E013 EPC Rulebook attribute.

    Account:
      type: object
      required:
        - Identification
        - Agent
      properties:
        Agent:
          type: string
          description:
            BIC of the Payee bank, can be used by the responding PSP for further internal routing. C002 EPC Rulebook attribute.
        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


    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.

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

    UUIDv4Identifier:
      type: string
      description: |
        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}$

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