openapi: 3.0.3
info:
  title: Holvi PSD2 Account Information Third Party Provider API
  version: '2.0'
  description: PSD2 (Payment Services Directive 2) API for licensed Third Party Providers (TPPs) to access Holvi customer payment accounts (AISP) and initiate SEPA / SEPA Instant / SWIFT payments (PISP) with Strong Customer Authentication, plus optional Verification of Payee (VOP). TPPs authenticate with an eIDAS QSEAL client certificate, a Holvi Client-Id/Client-Secret pair, and per-request HTTP message signatures (Draft Cavage HTTP Signatures v10, RSA-SHA256). End users (PSUs) grant consent through a redirect login flow that yields a JWT bearer access token.
  contact:
    name: Holvi Developer Support
    email: developer@holvi.com
    url: https://holvi-developer.zendesk.com/hc/en-gb
  x-api-evangelist:
    method: generated
    source: https://holvi.github.io/psd2-api/
    generated: '2026-07-19'
servers:
- url: https://api.psd2.holvi.com
  description: Production
security:
- HolviClientId: []
  HolviClientSecret: []
  HolviSignatureHeader: []
  HolviBearer: []
tags:
- name: Third Party Provider
  description: TPP certificate lifecycle.
paths:
  /api/v2/renew-certificate/:
    post:
      tags:
      - Third Party Provider
      operationId: renewCertificate
      summary: Renew a TPP client certificate
      description: Renews the eIDAS client certificate for a given application_id.
      security:
      - HolviBearer: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                new_certificate:
                  type: string
                  format: binary
                  description: New client certificate (.pem) file.
                application_id:
                  type: string
                  format: uuid
              required:
              - new_certificate
              - application_id
      responses:
        '200':
          description: Certificate renewed correctly
          content:
            application/json:
              schema:
                type: object
                properties:
                  application_id:
                    type: string
                    format: uuid
                  new_certificate:
                    type: string
        '400':
          description: Invalid certificate, unknown application ID, or certificate file too big
        '401':
          description: Unsuccessful authentication
components:
  securitySchemes:
    HolviClientId:
      type: apiKey
      in: header
      name: X-Holvi-Client-Id
      description: Client ID identifying the TPP application (from approved onboarding).
    HolviClientSecret:
      type: apiKey
      in: header
      name: X-Holvi-Client-Secret
      description: Client Secret authenticating the TPP (from approved onboarding).
    HolviSignatureHeader:
      type: apiKey
      in: header
      name: Signature
      description: Application-level HTTP message signature (Draft Cavage HTTP Signatures v10, RSA-SHA256, key >= 2048-bit) over (request-target), Host, Date [, Content-Type, Digest for write methods], keyId = Client-Id, using the eIDAS QSEAL certificate.
    HolviBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: PSU consent JWT access token from the consent token exchange.