Documentation

Welcome to the Validor Developer Documentation. Validor is an institutional-grade infrastructure for cryptographically binding EU Digital Identities to B2B transactions.

What is Validor?

Validor solves the "Invoice Impersonation" problem by requiring a cryptographic proof of identity for every high-value document exchanged. We act as a middleware between your ERP system (SAP, Oracle) and the European Digital Identity Framework.

Using Validor, you can:

• Verify Senders: Ensure an invoice actually came from the claimed entity using their EUDI Wallet.
• Protect Privacy: Use zero-knowledge hashing so Validor never sees the contents of your invoices.
• Generate Audit Trails: Automatically create certified PDF evidence reports for compliance.

Architecture

Validor operates on a "Trust but Verify" model. We do not store your documents. Instead, we sign hashes.

APP -> (Invoice Hash) -> VALIDOR API -> (QR Code) -> EUDI WALLET
                                                       |
        (Verified Identity) <- (OIDC4VP) <-------------+
                |
VALIDOR -> (Signed Audit Record) -> APP

Quick Start

To verify your first invoice, you'll need an API Key. Once obtained, you can initiate a verification session via a simple cURL command.

1. Initiate Verification

curl -X POST https://api.validor.eu/v1/verify-invoice \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_reference": "INV-1001",
    "invoice_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "amount_eur": 5000.00
  }'

2. Display QR Code

The API will return a qr_code_data string. Render this as a QR code for the user to scan with their EUDI Wallet.

3. Listen for Webhook

Once the user approves the request in their wallet, Validor will send a POST request to your configured webhook URL with the verification result.

Core Concepts

EUDI Wallet

The European Digital Identity (EUDI) Wallet is a secure mobile application that allows EU citizens and businesses to store and share verifiable credentials. It is the cornerstone of the eIDAS 2.0 regulation.

Validor supports all EUDI-compliant wallets that implement the OIDC4VP protocol. When a user scans a Validor QR code, they are proving their identity using government-issued credentials stored securely on their device.

OIDC4VP Protocol

OpenID for Verifiable Presentations (OIDC4VP) is the standard protocol used to request and present digital credentials. It extends the OpenID Connect flow to support decentralized identity.

In a Validor verification flow:

• Validor acts as the Verifier: We generate a presentation request.
• The Wallet acts as the Holder: It receives the request and prompts the user for consent.
• The Issuer (Government): Cryptographically signed the credentials beforehand.

Zero-Knowledge Proofs

Validor employs a zero-knowledge architecture for document verification. We never ask you to upload the actual PDF of an invoice. Instead, we ask for a SHA-256 hash.

This ensures that sensitive financial data (line items, prices, bank details) never leaves your infrastructure. We only verify that someone with a valid identity has signed that specific document fingerprint.

Integration

API Overview

The Validor API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL: https://api.validor.eu/v1

Webhooks

Webhooks are the primary way to receive verification results. Since wallet interactions are asynchronous (the user might take a minute to find their phone), you should not poll the API.

Configure your webhook endpoint in the dashboard. Payload example:

{
  "event": "verification.succeeded",
  "data": {
    "session_id": "sess_12345",
    "invoice_ref": "INV-2026-001",
    "verified_at": "2026-02-16T14:30:00Z",
    "user_claims": {
      "given_name": "François",
      "family_name": "Cardinaud",
      "birth_date": "1990-01-01"
    }
  }
}

SDKs

We provide official SDKs to simplify integration. These libraries handle hashing, API communication, and polling fallbacks if webhooks cannot be used.

• Node.js: npm install @validor/node
• Python: pip install validor-sdk
• Browser (JS): <script src="https://js.validor.eu/v1"></script>

Changelog