Onboarding a New TPP

This guide walks you through onboarding as a new TPP (Third Party Provider) using our hosted eIDAS broker as your Technical Service Provider (TSP) for Account Information Services.

Before You Start

What We Provide

We operate as your TSP — the technical infrastructure layer that connects to ASPSP (bank) APIs on your behalf. You remain the regulated entity, responsible for your PSD2 license, your relationship with PSUs (Payment Service Users), and compliance with GDPR and DORA obligations.

Our hosted eIDAS broker handles:

• Secure storage and usage of your eIDAS certificates
• TLS mutual authentication (QWAC) and request signing (QSealC) with ASPSPs
• Connectivity to ASPSP PSD2 APIs across supported European markets

Prerequisites

Before starting, make sure you have:

1. A valid AISP license (or Credit Institution license with AIS passporting rights) from your National Competent Authority (NCA). Your authorization must be visible in the EBA register.
2. eIDAS certificates — a QWAC and a QSealC from a Qualified Trust Service Provider (QTSP), containing your PSD2 license number, NCA name, and the PSP_AI role. If you don't have certificates yet, see Obtaining eIDAS Certificates.
3. Terms of Service and Privacy Notice that you present to PSUs when requesting consent to access their account data.
4. An API key we issue during the contracting phase.

Step 1: Obtain eIDAS Certificates

If you already have valid QWAC and QSealC certificates, skip to Step 2.

What Are QWAC and QSealC?

Two qualified certificates defined under the eIDAS Regulation (EU 910/2014) and required by PSD2 for TPP identification:

• QWAC (Qualified Certificate for Website Authentication) — used at the transport layer (mutual TLS). When our broker connects to a bank's API, the QWAC is presented during the TLS handshake to prove the connection is from a licensed TPP.
• QSealC (Qualified Certificate for Electronic Seal) — used at the application layer (HTTP request signing). API requests are digitally signed with the QSealC private key, providing non-repudiation — cryptographic proof that a specific TPP authorized a specific request.

How to Get Them

1. Choose a QTSP. The European Commission publishes trusted lists per member state. Filter by "Qualified certificate for electronic seal" and "Qualified certificate for website authentication." Common QTSPs in the open banking ecosystem include Buypass, D-Trust, Digidentity, and QuoVadis (DigiCert).
2. Generate a Certificate Signing Request (CSR). A CSR bundles your public key with your identity information (legal name, PSD2 license number, country, roles). You generate a key pair locally — the private key stays with you — and send the CSR to the QTSP. Most QTSPs provide tooling for PSD2-compliant CSRs following the ETSI TS 119 495 standard.
3. Submit the CSR to the QTSP. They verify your NCA registration and organizational identity, then issue the signed certificates. Expect a few days to a few weeks.
4. You'll receive a QWAC certificate + private key, and a QSealC certificate + private key. Keep the private keys secure — you need them in the next step.

Step 2: Upload Your Certificates

We provide a secure upload mechanism that protects your certificate private keys end-to-end. Our backend never sees your certificates in plaintext.

How It Works

The upload uses hybrid encryption with a dedicated upload script we provide:

1. The script fetches an RSA public key from our API (GET /eidas/public-key).
2. It generates a random AES-256 key and IV locally.
3. Your certificate files are encrypted with AES-256-GCM (authenticated encryption — tamper-proof).
4. The AES key is encrypted with RSA-OAEP using our public key.
5. The encrypted payload is sent to our API (POST /eidas/certificate).

On our side, the backend forwards the encrypted blob — without ever decrypting it — to an isolated AWS Lambda function. The Lambda decrypts using a private key stored in AWS Secrets Manager, validates the certificates, and stores them securely.

Running the Upload

python upload_eidas_certs.py \
  --api-key YOUR_API_KEY \
  --qwac-cert path/to/qwac.pem \
  --qwac-key path/to/qwac-private.key \
  --qseal-cert path/to/qseal.pem \
  --qseal-key path/to/qseal-private.key

Use --dry-run to verify the upload without persisting anything.

What We Validate

Before storing your certificates, we check:

• Certificates are well-formed X.509
• Each private key matches its corresponding certificate
• Certificates are not expired
• eIDAS QcStatement OIDs are present (QWAC: 0.4.0.194112.1.4, QSealC: 0.4.0.194112.1.2)

If any validation fails, we return specific error messages so you can correct the issue.

How We Store Them

Each certificate and key is stored as a separate secret in AWS Secrets Manager with strict resource policies. Only the eIDAS broker service (which calls ASPSP APIs) and the Lambda function (which processes uploads) can access these secrets — even users with AWS administrator permissions cannot read or modify them.

Step 3: ASPSP Onboarding

Once your certificates are uploaded and validated, we begin onboarding you to the ASPSPs (banks) you want to connect to.

Provide Your Target ASPSP List

Let us know which banks and markets you need connectivity to. We handle the onboarding process, which varies by ASPSP:

• Automated (certificate-only) banks — many Berlin Group ASPSPs identify the TPP purely from the eIDAS certificate. No explicit registration step is needed. These work immediately once your certificates are in our broker.
• Dynamic Client Registration (DCR) banks — require an API-based registration call that returns client credentials (client_id, client_secret). We execute DCR on your behalf and store the resulting credentials alongside your certificates.
• Manual developer portal banks — require registration through a web portal, sometimes with manual approval. We handle this for you, using the identity information from your certificates and the contact details you provide.

What You Need to Provide

• Company details and regulatory information
• Contact email for ASPSP communications (we manage ASPSP correspondence on your behalf)
• Redirect URIs for PSU authentication flows
• Your logo (some ASPSPs display this on their consent screens)

Step 4: Integration and Testing

Testing with test configurations

Before going live, run end-to-end tests using test configurations we provision alongside your production config. Test runs hit the real ASPSP integrations we maintain, so you validate the actual flow your PSUs will experience:

• PSU authentication end-to-end with real bank logins (use your own test accounts)
• Account and transaction data retrieval, including the exact response shape
• Consent lifecycle (creation, usage, expiry, revocation)

Edge cases with the mock ASPSP

Some failure modes — declined consents, timeouts, backend errors, expired consents — are hard to reproduce reliably against real ASPSPs. For these, run your tests against se-demo-psd2, our mock ASPSP that lets you trigger specific failure scenarios on demand. Use it to verify your application handles the unhappy paths correctly before they show up in production.

Go-Live Checklist

Before going live, confirm:

• eIDAS certificates are uploaded and validated
• ASPSP onboarding is complete for your target banks
• End-to-end tests pass against your test configurations
• Your Terms of Service and Privacy Notice are finalized
• Monitoring and alerting is configured
• You've told us your go-live date so we can allocate support resources

Obtaining eIDAS Certificates

Choosing a QTSP

Not all QTSPs on the EU trusted lists issue PSD2-specific certificates. When selecting one, confirm they support:

• The PSD2 QcStatement extensions per ETSI TS 119 495
• Both QWAC and QSealC certificate types
• Your specific PSD2 roles (PSP_AI for AIS)

Renewal

Certificates are typically valid for one to two years. Start the renewal process at least one month before expiry to avoid service disruption.

Certificate File Format

We accept certificates in PEM format. You should have four files:

Private keys must be in RSA format; certificate files must include the complete chain.