openapi: 3.0.2
info:
  title: Worldline VoP - Account Holder Data Management API
  version: 0.0.1 BETA
  description: |
    The Worldline VoP API for Account Data Management describes the interface exposed by the Worldline VoP Hub, for PSPs that want to delegate the management and storage of account holder identification to Worldline, to fulfill the role of responding PSP in the VoP EPC ecosystem.

tags:
  - name: "Account Holder Data Management API"

paths:
  /account-holders:
    get:
      tags:
        - "Account Holder Data Management API"
      summary: Get a set of account-holders, with optional filtering and pagination
      parameters:
        - name: limit
          in: query
          description: |
            The maximum number of items to return per page. Default = 500, Max = 2000 (any higher value will be replaced by Max).
          required: false
          schema:
            type: integer
            format: int32
        - name: page
          in: query
          description: |
            The page number to retrieve.
          required: false
          schema:
            type: integer
            format: int32
        - name: account-holding-psp-reference
          in: query
          description: |
            Allows to return a single account holder resource based on the stored AccountHoldingPSPReference.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  AccountHolders:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccountHolderForGet'
                  MetaData:
                    $ref: '#/components/schemas/PaginationMetaData'
                  Links:
                    $ref: '#/components/schemas/PaginationLinks'
    post:
      tags:
        - "Account Holder Data Management API"
      summary: Create a new account-holder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountHolder'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                required:
                  - AccountHolderId
                properties:
                  AccountHolderId:
                    type: string
                    description: The unique identifier of the account holder
                        

  /account-holders/bulk:
    post:
      tags:
        - "Account Holder Data Management API"
      summary: Create new account-holders in bulk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                AccountHolders:
                  type: array
                  items:
                    $ref: '#/components/schemas/AccountHolder'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  AccountHolders:
                    type: array
                    items:
                      type: object
                      required: 
                        - AccountHoldingPSPReference
                      properties:
                        AccountHolderId:
                          type: string
                          description: The unique identifier of the account holder. Returned if the creation was successful
                        AccountHoldingPSPReference:
                          type: string
                          description: The reference of the PSP holding the account holder data
                        Error:
                          type: string
                          description: The error message if the account holder creation failed
                        

  /account-holders/{accountHolderId}:
    get:
      tags:
        - "Account Holder Data Management API"
      summary: Get an account holder by accountHolderId
      parameters:
        - name: accountHolderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountHolderForGet'
        '404':
          description: Not Found
    put:
      tags:
        - "Account Holder Data Management API"
      summary: Update and replace a complete account-holder by accountHolderId
      description: This endpoint allows for a complete replacement of an account holder. All data fields tied to the account holder need to be passed, previous information will be erased (see PATCH method for partial updates). If the account holder does not exist, the request will result in an error.
      parameters:
        - name: accountHolderId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountHolder'
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
    patch:
      tags:
        - "Account Holder Data Management API"
      summary: Partially update an account holder by accountHolderId
      description: This endpoint allows for a partial update of an account holder resource. Only the data fields needing an update must be passed, previous information will be erased (see PUT method for resource replacement). In the case of arrays like Names or AdditionalIdentification, the previous array is fully replaced with the new one. If the account holder does not exist, the request will result in an error.
      parameters:
        - name: accountHolderId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountHolderForPatch'
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
    delete:
      tags:
        - "Account Holder Data Management API"
      summary: Delete an item by accountHolderId
      parameters:
        - name: accountHolderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No Content

components:
  schemas:
    AccountHolder:
      type: object
      required:
        - Account
        - Names
        - AccountHoldingPSPReference
      properties :
        AccountHoldingPSPReference:
          type: string
          description: |
            Reference of the PSP holding the account holder data. Must be unique.
        Account:
          $ref: '#/components/schemas/Account'
        Names:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 140
          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'
        
    AccountHolderForPatch:
      type: object
      properties :
        AccountHoldingPSPReference:
          type: string
          minLength: 1
          maxLength: 140
          description: |
            Reference of the PSP holding the account holder data. Must be unique.
        Account:
          $ref: '#/components/schemas/Account'
        Names:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 140
          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'

    AccountHolderForGet:
      type: object
      required :
        - AccountHolderId
        - AccountHoldingPSPReference
        - Account
        - Names
      properties :
        AccountHolderId:
          type: string
          description: |
            Unique identifier of the account holder.
        AccountHoldingPSPReference:
          type: string
          description: |
            Reference of the PSP holding the account holder data. Must be unique.
        Account:
          $ref: '#/components/schemas/Account'
        Names:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 140
          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'

    PaginationMetaData:
      type: object
      properties:
        CurrentPage:
          type: integer
          format: int32
          description: Current page number
        PageSize:
          type: integer
          format: int32
          description: Number of Account Holders returned
        TotalPages:
          type: integer
          format: int32
          description: Total number of pages available
        TotalItems:
          type: integer
          format: int32
          description: Total number of Account Holders available

    PaginationLinks:
      type: object
      properties:
        First:
          type: string
          description: Link to the first page
        Previous:
          type: string
          description: Link to the previous page
        Next:
          type: string
          description: Link to the next page
        Last:
          type: string
          description: Link to the last page

    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.

    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
    
    Link:
      required:
        - Href
      type: object
      additionalProperties: false
      properties:
        Href:
          maxLength: 1024
          minLength: 1
          type: string