openapi: 3.0.4
info:
  title: VoP - Account Data Management
  version: 1.0.0-RC
  description: |
    The Worldline VoP API for Account Data Management describes the interface exposed by the Worldline VoP Solution. It is intended for PSPs that want to delegate the management and storage of account holder identification to Worldline in order to fulfill the role of responding PSP in the VoP EPC ecosystem.

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

security:
  - oAuthSSO: [ VOP ]

paths:
  /v1/account-holders:
    get:
      tags:
        - "Account Holder Data Management API"
      summary: Get a set of account-holders, with optional filtering and pagination
      operationId: getAccountHolders
      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'
        '400':
          description: |
            Bad request
            The result code is given, if there is anything wrong with the request sent by the client, i.e. missing fields or invalid information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: |
            Unauthorized
            The result code is given, if the client could not be authorized, i.e. the access token or the x-jws-signature header could not be verified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: |
            Not found.
            The result code is given, if the requested account(s) could not be retrieved by the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: |
            Internal Server error
            The result code is given, if there was a problem on server side handling the request. The response body might contain additional information. Try the request again later, if the problem persists notify your contact person of the problem.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    post:
      tags:
        - "Account Holder Data Management API"
      summary: Create a new account-holder
      operationId: createAccountHolder
      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
        '400':
          description: |
            Bad request
            The result code is given, if there is anything wrong with the request sent by the client, i.e. missing fields or invalid information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: |
            Unauthorized
            The result code is given, if the client could not be authorized, i.e. the access token or the x-jws-signature header could not be verified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: |
            Internal Server error
            The result code is given, if there was a problem on server side handling the request. The response body might contain additional information. Try the request again later, if the problem persists notify your contact person of the problem.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'

  /v1/account-holders/bulk:
    post:
      tags:
        - "Account Holder Data Management API"
      summary: Create new account-holders in bulk
      operationId: createAccountHolders
      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
        '400':
          description: |
            Bad request
            The result code is given, if there is anything wrong with the request sent by the client, i.e. missing fields or invalid information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: |
            Unauthorized
            The result code is given, if the client could not be authorized, i.e. the access token or the x-jws-signature header could not be verified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: |
            Internal Server error
            The result code is given, if there was a problem on server side handling the request. The response body might contain additional information. Try the request again later, if the problem persists notify your contact person of the problem.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'

  /v1/account-holders/{accountHolderId}:
    get:
      tags:
        - "Account Holder Data Management API"
      summary: Get an account holder by accountHolderId
      operationId: getAccountHolderById
      parameters:
        - name: accountHolderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountHolderForGet'
        '400':
          description: |
            Bad request
            The result code is given, if there is anything wrong with the request sent by the client, i.e. missing fields or invalid information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: |
            Unauthorized
            The result code is given, if the client could not be authorized, i.e. the access token or the x-jws-signature header could not be verified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: |
            Not found.
            The result code is given, if the requested account  could not be retrieved by the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: |
            Internal Server error
            The result code is given, if there was a problem on server side handling the request. The response body might contain additional information. Try the request again later, if the problem persists notify your contact person of the problem.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    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.
      operationId: replaceAccountHolder
      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
        '400':
          description: |
            Bad request
            The result code is given, if there is anything wrong with the request sent by the client, i.e. missing fields or invalid information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: |
            Unauthorized
            The result code is given, if the client could not be authorized, i.e. the access token or the x-jws-signature header could not be verified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: |
            Not found.
            The result code is given, if the account to be replaced could does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: |
            Internal Server error
            The result code is given, if there was a problem on server side handling the request. The response body might contain additional information. Try the request again later, if the problem persists notify your contact person of the problem.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    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.
      operationId: updateAccountHolder
      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
        '400':
          description: |
            Bad request
            The result code is given, if there is anything wrong with the request sent by the client, i.e. missing fields or invalid information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: |
            Unauthorized
            The result code is given, if the client could not be authorized, i.e. the access token or the x-jws-signature header could not be verified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: |
            Not found.
            The result code is given, if the account to patch could not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: |
            Internal Server error
            The result code is given, if there was a problem on server side handling the request. The response body might contain additional information. Try the request again later, if the problem persists notify your contact person of the problem.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    delete:
      tags:
        - "Account Holder Data Management API"
      summary: Delete an item by accountHolderId
      operationId: removeAccountHolder
      parameters:
        - name: accountHolderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No Content
        '400':
          description: |
            Bad request
            The result code is given, if there is anything wrong with the request sent by the client, i.e. missing fields or invalid information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: |
            Unauthorized
            The result code is given, if the client could not be authorized, i.e. the access token or the x-jws-signature header could not be verified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: |
            Internal Server error
            The result code is given, if there was a problem on server side handling the request. The response body might contain additional information. Try the request again later, if the problem persists notify your contact person of the problem.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'

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:
    Account:
      type: object
      required:
        - Identification
        - Agent
      properties:
        Agent:
          type: string
          pattern: '^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$'
          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
          pattern: '^(IBAN|BBAN)$'
          default: 'IBAN'
          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

    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
          minItems: 1
          items:
            type: string
            minLength: 1
            maxLength: 140
            nullable: false
          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'

    AdditionalIdentifier:
      type: object
      required:
        - CodeType
        - Code
      properties:
        CodeType:
          type: string
          minLength: 1
          description: |
            Type of the additional identification code, as defined in ISO standard XXXXX. Example : VAT, TAX... E013 EPC Rulebook attribute.
        Code:
          type: string
          minLength: 1
          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.

    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

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