If you have ever built a SaaS product that sells to European businesses, you have hit VIES. The VAT Information Exchange System is the European Commission's service for validating EU VAT numbers. Every B2B transaction that involves reverse charge, every checkout flow that needs to verify a customer's tax status, every KYB onboarding that must confirm a company is real — all of it runs through VIES.

And VIES is unreliable.

Not unreliable in the "sometimes slow" sense. Unreliable in the "Germany generates the vast majority of all VIES errors, the entire system has a global concurrency limit, and two of the largest economies in the EU refuse to return company names" sense.

This post is a technical breakdown of what makes VIES difficult to work with, the specific failure modes we have documented, and the architecture decisions we made at EuroValidate to build a reliable layer on top of it.

How VIES actually works

VIES is not a single database. It is a SOAP-based routing layer operated by the European Commission. When you send a VAT validation request, VIES forwards it to the national tax authority of the relevant member state. Germany's request goes to the Bundeszentralamt fur Steuern. France's goes to the DGFiP. Each of the 27 EU member states runs its own backend.

This architecture is the root cause of most reliability problems. VIES is only as available as the weakest national system online at any given moment.

The WSDL endpoint is:

https://ec.europa.eu/taxation_customs/vies/checkVatService.wsdl

A typical SOAP request looks like this:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:urn="urn:ec.europa.eu:taxud:vies:services:checkVat:types">
   <soapenv:Body>
      <urn:checkVat>
         <urn:countryCode>NL</urn:countryCode>
         <urn:vatNumber>820646660B01</urn:vatNumber>
      </urn:checkVat>
   </soapenv:Body>
</soapenv:Envelope>

If the Dutch backend is up, you get a response in 200-2000ms. If it is down, you get a SOAP fault. If too many people are querying it simultaneously, you get MS_MAX_CONCURRENT_REQ. If the entire VIES router is overloaded, you get SERVICE_UNAVAILABLE.

The specific problems

Problem 1: MS_MAX_CONCURRENT_REQ is a global limit

This is the one that surprises most developers. When a member state backend returns MS_MAX_CONCURRENT_REQ, it does not mean your application is sending too many requests. It means the entire country's backend is overloaded — across all consumers worldwide. Every fintech startup, every ERP system, every government cross-check, every tax software vendor — all sharing a single concurrency pool per country.

There is nothing you can do about this except retry with backoff and cache aggressively.

Problem 2: Germany and Spain never return company names

Germany and Spain have national data protection laws that prohibit VIES from returning trader name and address information. When you validate a German VAT number like DE123456789, the response will confirm valid/invalid but the name and address fields will be empty.

This is not a bug. This is permanent behavior mandated by law.

In our VIES client, we handle this explicitly:

# Countries whose national systems do not return name/address
_NO_TRADER_DATA_COUNTRIES: frozenset[str] = frozenset({"DE", "ES"})

For these countries, we fall back to the GLEIF API to resolve company identity. GLEIF (Global Legal Entity Identifier Foundation) provides company data for any entity that holds an LEI. It is free, requires no authentication, and returns structured JSON instead of SOAP.

Problem 3: Greece uses EL, not GR

Every ISO 3166-1 standard says Greece is GR. VIES uses EL (from the Greek name "Ellada"). If you send GR to VIES, you get an INVALID_INPUT fault. If your system stores country codes as ISO 3166 (as it should), you need bidirectional mapping.

This is a small thing, but it has broken countless integrations. We have seen production systems that worked for 26 countries and silently failed for Greece for months before anyone noticed.

Our mapping is explicit:

_COUNTRY_TO_VIES: dict[str, str] = {"GR": "EL"}
_VIES_TO_COUNTRY: dict[str, str] = {"EL": "GR"}

Both directions. Always. Every VAT number input that starts with GR gets mapped to EL before hitting VIES. Every response from VIES with EL gets mapped back to GR before reaching the client.

Problem 4: Northern Ireland dual status

Northern Ireland exists in both EU customs territory (via the Windsor Framework) and UK VAT territory simultaneously. A Northern Irish business might have:

• An XI EORI number (EU customs)
• A GB VAT number (UK tax)

Your system needs to handle both. An XI prefix routes to the EU EORI validation system. A GB prefix routes to HMRC's REST API. Same company, different systems, different protocols (SOAP vs REST).

Problem 5: Territory exceptions

Not everything inside an EU country is inside the EU VAT territory.

• Monaco is treated as France for VAT purposes. A Monaco-based company uses an FR VAT prefix.
• The Canary Islands are Spanish territory but outside the EU VAT area. A company in Las Palmas does not charge EU VAT.
• Mount Athos is Greek territory but outside the EU VAT area.
• Campione d'Italia and Lake Lugano are Italian territory but outside the EU VAT area.

If your checkout flow does not account for these, you will either overcharge or undercharge VAT. Both are compliance violations.

Problem 6: VIES SOAP returns "---" instead of null

When trader data is unavailable (but the country does nominally return it), VIES does not send an empty string or omit the field. It sends the literal string "---". If you are not filtering for this, your database now has company names that are three dashes.

if name and name.strip() in ("---", ""):
    name = None
if address and address.strip() in ("---", ""):
    address = None

Our architecture: how we built around it

When we designed EuroValidate, we started from a simple premise: the upstream is unreliable, so every layer of our system must assume it can fail at any moment.

Per-country circuit breakers

We run 28 independent circuit breakers for VIES — one per EU member state (with GR and EL aliased to the same breaker). Plus one for the EC EORI endpoint and one for HMRC. That is 30 circuit breakers total.

When Germany is down (which happens frequently), the breaker for DE trips to OPEN state. Requests for French, Dutch, or Italian VAT numbers continue flowing unaffected. Germany being down does not equal Europe being down.

Each breaker uses the same configuration:

• fail_max: 5 consecutive failures before tripping
• reset_timeout: 60 seconds before allowing a probe request
• State machine: CLOSED (normal) -> OPEN (blocking) -> HALF_OPEN (probing) -> CLOSED

breaker_registry = CircuitBreakerRegistry()
breaker = breaker_registry.get_vies_breaker("DE")
# If DE has failed 5 times, this raises CircuitBreakerError immediately
# No waiting, no timeout, no wasted connection

Dual-layer cache

Every successful VIES response is cached in two layers:

1. Redis (hot cache): sub-millisecond reads, TTL of 24 hours for VAT data
2. PostgreSQL (persistent cache): survives Redis restarts, used as fallback

The lookup order is: Redis -> PostgreSQL -> upstream VIES.

If VIES is down and the circuit breaker is open, we serve from cache with reduced confidence. The client always gets a response. The confidence score tells them how much to trust it.

Confidence scoring

Every EuroValidate response includes a confidence field: HIGH, MEDIUM, LOW, or UNKNOWN.

The rules are deterministic:

• HIGH: Live response from upstream, or deterministic offline check (like IBAN MOD 97), or cached data less than 1 hour old
• MEDIUM: Cached data between 1 and 24 hours old, or cross-referenced sources that agree
• LOW: Cached data older than 24 hours (stale)
• UNKNOWN: Upstream unreachable and no cached data exists

Cross-referencing can promote MEDIUM to HIGH. If both VIES and GLEIF agree on a company's identity, and the VIES data is cached within 24 hours, the confidence gets boosted. But cross-referencing never promotes LOW or UNKNOWN — the data is too stale to trust regardless of source agreement.

def score_cross_referenced(primary, secondary, entities_match):
    if not entities_match:
        return primary  # No boost on mismatch
    if (primary.level == ConfidenceLevel.MEDIUM
        and secondary.level >= ConfidenceLevel.MEDIUM):
        return HIGH  # MEDIUM -> HIGH when sources agree
    return primary

This lets clients make informed decisions. A checkout flow might accept HIGH and MEDIUM but flag LOW for manual review. A KYB pipeline might require HIGH only.

Graceful degradation

EuroValidate never returns a bare HTTP 500. If the upstream is down, we return cached data with reduced confidence and an upstream_status field that tells the client what happened.

Compare this to calling VIES directly:

Raw VIES (when Germany is down):

<soap:Fault>
  <faultcode>soap:Server</faultcode>
  <faultstring>MS_UNAVAILABLE</faultstring>
</soap:Fault>

Your application crashes or returns a 500 to your user. No data. No context. No fallback.

EuroValidate (same scenario):

{
  "success": true,
  "data": {
    "valid": true,
    "country_code": "DE",
    "vat_number": "812526315",
    "name": null,
    "address": null
  },
  "meta": {
    "confidence": "MEDIUM",
    "source": "cache_postgresql",
    "cached": true,
    "response_time_ms": 3,
    "last_verified": "2026-04-04T14:30:00Z",
    "upstream_status": "vies_de: unavailable"
  },
  "request_id": "req_7f3k2m"
}

The client gets data. They know it is cached. They know the upstream is down. They know the confidence level. They can make a business decision.

Retry with exponential backoff and jitter

For transient errors (MS_MAX_CONCURRENT_REQ, TIMEOUT, MS_UNAVAILABLE), we retry up to 3 times with exponential backoff plus jitter:

@retry(
    retry=retry_if_exception_type(ViesTransientError),
    stop=stop_after_attempt(3),
    wait=wait_exponential_jitter(initial=0.5, max=5, jitter=1),
    reraise=True,
)
def check_vat(self, country_code, vat_number):
    ...

The jitter prevents thundering herd when VIES comes back up after an outage. Without jitter, every cached-out client retries at the exact same interval, recreating the overload.

Async execution

VIES uses SOAP, which means zeep, which is synchronous. In an async FastAPI application, blocking the event loop on a SOAP call would kill throughput. We run all zeep calls in a bounded thread pool:

_executor = ThreadPoolExecutor(max_workers=10, thread_name_prefix="vies")

async def validate_vat(full_vat: str) -> ViesResult:
    vies_cc, vat_number = _normalise_input(full_vat)
    loop = asyncio.get_running_loop()
    result = await loop.run_in_executor(
        _executor, _soap_client.check_vat, vies_cc, vat_number
    )
    return result

Ten concurrent VIES calls maximum. Enough to handle burst traffic. Not enough to exhaust connections or contribute to MS_MAX_CONCURRENT_REQ.

The result

EuroValidate turns an unreliable SOAP service into a reliable REST API. One endpoint. JSON responses. Confidence scores. Graceful degradation. No SOAP, no XML parsing, no country-code mapping, no retry logic in your application code.

The numbers from our system:

• 130 EU banks in the IBAN registry for instant BIC/bank lookup
• 30 independent circuit breakers (28 VIES + 1 EORI + 1 HMRC)
• 4 confidence levels with deterministic scoring rules
• 3-layer lookup: Redis (sub-ms) -> PostgreSQL (low ms) -> upstream (200-2000ms)
• IBAN validation: fully offline, deterministic, always HIGH confidence

If you are building anything that touches EU VAT, IBAN, or EORI validation, you can try EuroValidate for free at eurovalidate.com. The API docs are at api.eurovalidate.com/docs.

We built this because we got tired of writing the same VIES workarounds in every project. Now you do not have to either.

If you sell B2B in the European Union, you are required to validate your customer's VAT number before applying the reverse charge mechanism. This is not optional. The EU VAT Directive mandates that you verify the number is valid and active before zero-rating an intra-Community supply.

Most Stripe integrations skip this step or do it incorrectly. The result: either you charge VAT when you should not (your customer complains) or you do not charge VAT when you should (your tax authority complains). Both are bad.

This guide shows you how to add proper EU VAT validation to a Stripe checkout flow using EuroValidate. We will cover validation, reverse charge logic, and audit trail storage. Python and Node.js examples included.

What you need

• A Stripe account with a PaymentIntent-based checkout
• An EuroValidate API key (free tier: 100 calls/month) -- get one at eurovalidate.com
• Basic understanding of EU reverse charge rules

How EU reverse charge works (30-second version)

When a VAT-registered business in EU Country A sells to a VAT-registered business in EU Country B, the seller does not charge VAT. Instead, the buyer self-assesses VAT in their own country. This is the reverse charge mechanism.

To apply reverse charge, you must:

1. Confirm the buyer's VAT number is valid and active
2. Confirm the buyer is in a different EU member state than you
3. Keep proof of validation (timestamp, result, confidence level) for your records

If validation fails or the buyer is in the same country as you, charge the standard VAT rate.

Step 1: Install the SDK

# Python
pip install eurovalidate

# Node.js
npm install @eurovalidate/sdk

Or call the API directly -- no SDK required:

curl -H "X-API-Key: your_api_key" \
  https://api.eurovalidate.com/v1/vat/NL820646660B01

Step 2: Validate the VAT number before payment

The VAT number should be validated before you create the Stripe PaymentIntent. This way you know the correct amount to charge.

Python

import eurovalidate
import stripe

eurovalidate.api_key = "ev_live_your_key"
stripe.api_key = "sk_live_your_key"

YOUR_COUNTRY = "PT"  # Your business is in Portugal
STANDARD_VAT_RATE = 0.23  # Portuguese standard rate

async def create_checkout(customer_vat: str, amount_cents: int, currency: str = "eur"):
    """
    Validate VAT, apply reverse charge if eligible, create PaymentIntent.
    """
    vat_result = None
    apply_reverse_charge = False

    if customer_vat:
        # Validate the customer's VAT number
        vat_result = eurovalidate.vat.validate(customer_vat)

        if vat_result.data.valid and vat_result.meta.confidence in ("HIGH", "MEDIUM"):
            customer_country = vat_result.data.country_code
            # Reverse charge: valid VAT + different EU country
            if customer_country != YOUR_COUNTRY:
                apply_reverse_charge = True

    # Calculate final amount
    if apply_reverse_charge:
        total_cents = amount_cents  # No VAT added
        vat_cents = 0
    else:
        vat_cents = int(amount_cents * STANDARD_VAT_RATE)
        total_cents = amount_cents + vat_cents

    # Create the Stripe PaymentIntent
    intent = stripe.PaymentIntent.create(
        amount=total_cents,
        currency=currency,
        metadata={
            "vat_number": customer_vat or "",
            "vat_valid": str(vat_result.data.valid) if vat_result else "not_provided",
            "vat_confidence": vat_result.meta.confidence if vat_result else "N/A",
            "reverse_charge": str(apply_reverse_charge),
            "vat_amount_cents": str(vat_cents),
            "validation_request_id": vat_result.request_id if vat_result else "",
        },
    )

    return {
        "client_secret": intent.client_secret,
        "total_cents": total_cents,
        "vat_cents": vat_cents,
        "reverse_charge": apply_reverse_charge,
    }

Node.js

const EuroValidate = require("@eurovalidate/sdk");
const Stripe = require("stripe");

const ev = new EuroValidate("ev_live_your_key");
const stripe = new Stripe("sk_live_your_key");

const YOUR_COUNTRY = "PT";
const STANDARD_VAT_RATE = 0.23;

async function createCheckout(customerVat, amountCents, currency = "eur") {
  let vatResult = null;
  let applyReverseCharge = false;

  if (customerVat) {
    vatResult = await ev.vat.validate(customerVat);

    if (
      vatResult.data.valid &&
      ["HIGH", "MEDIUM"].includes(vatResult.meta.confidence)
    ) {
      const customerCountry = vatResult.data.country_code;
      if (customerCountry !== YOUR_COUNTRY) {
        applyReverseCharge = true;
      }
    }
  }

  const vatCents = applyReverseCharge
    ? 0
    : Math.round(amountCents * STANDARD_VAT_RATE);
  const totalCents = amountCents + vatCents;

  const intent = await stripe.paymentIntents.create({
    amount: totalCents,
    currency,
    metadata: {
      vat_number: customerVat || "",
      vat_valid: vatResult ? String(vatResult.data.valid) : "not_provided",
      vat_confidence: vatResult ? vatResult.meta.confidence : "N/A",
      reverse_charge: String(applyReverseCharge),
      vat_amount_cents: String(vatCents),
      validation_request_id: vatResult ? vatResult.request_id : "",
    },
  });

  return {
    clientSecret: intent.client_secret,
    totalCents,
    vatCents,
    reverseCharge: applyReverseCharge,
  };
}

Step 3: Store validation proof for tax audit

EU tax authorities can request proof that you validated a VAT number before applying reverse charge. The proof should include:

• The VAT number that was validated
• The validation result (valid/invalid)
• The timestamp of validation
• A consultation number (if available via checkVatApprox)
• The confidence level of the result

EuroValidate returns all of this in the API response. Store it alongside your invoice record:

# After successful payment, store the validation record
def store_validation_proof(payment_intent_id: str, vat_result):
    """
    Store in your database for tax audit compliance.
    """
    record = {
        "payment_intent_id": payment_intent_id,
        "vat_number": f"{vat_result.data.country_code}{vat_result.data.vat_number}",
        "valid": vat_result.data.valid,
        "company_name": vat_result.data.name,
        "company_address": vat_result.data.address,
        "confidence": vat_result.meta.confidence,
        "source": vat_result.meta.source,
        "last_verified": vat_result.meta.last_verified,
        "request_id": vat_result.request_id,
        "validated_at": datetime.utcnow().isoformat(),
    }
    # Insert into your database
    db.validation_proofs.insert(record)

The request_id field (req_abc123 format) is unique per request. If a tax authority questions a specific transaction, you can trace back to the exact validation that occurred.

Handling edge cases

Edge case 1: VIES is down

VIES goes down regularly. When it does, EuroValidate returns cached data with a reduced confidence score. Your checkout should handle this:

if vat_result.meta.confidence == "UNKNOWN":
    # No cached data, upstream unreachable
    # Option A: Charge VAT and refund later if validated
    # Option B: Allow checkout but flag for manual review
    apply_reverse_charge = False
    flag_for_review = True

elif vat_result.meta.confidence == "LOW":
    # Stale cache (>24h old)
    # The data might be outdated -- proceed with caution
    apply_reverse_charge = True
    flag_for_review = True

The confidence level gives you a framework for deciding. HIGH and MEDIUM are safe for automated decisions. LOW and UNKNOWN should trigger manual review or a conservative fallback (charge VAT, refund if validated later).

Edge case 2: Germany and Spain

Germany and Spain do not return company names through VIES (national data protection law). The VAT number will validate as valid/invalid, but name and address will be null.

If you need company identity for German or Spanish customers, use the /v1/company endpoint, which checks GLEIF:

# VAT validated but no name (Germany)
if vat_result.data.valid and vat_result.data.name is None:
    company = eurovalidate.company.lookup(customer_vat)
    company_name = company.data.legal_name if company.success else None

Edge case 3: Invalid VAT format

If the customer enters a malformed VAT number, EuroValidate returns an error with a clear message. Handle this in your frontend:

const result = await ev.vat.validate(customerVat);

if (!result.success) {
  // Show error to user
  showError("Please enter a valid EU VAT number (e.g., NL820646660B01)");
  return;
}

if (!result.data.valid) {
  // VAT number is well-formed but not registered/active
  showWarning("This VAT number is not currently active. VAT will be charged.");
}

Edge case 4: Same-country B2B

If the customer's VAT number is from the same country as your business, reverse charge does not apply. You charge domestic VAT as usual:

if customer_country == YOUR_COUNTRY:
    # Same country: charge domestic VAT, no reverse charge
    apply_reverse_charge = False

This is a common mistake. Reverse charge is only for cross-border intra-Community supplies.

Validating at the right moment

Validate the VAT number as early as possible in your checkout flow, ideally when the customer enters it (not after they click "Pay"). This gives you time to:

1. Show the correct total (with or without VAT) before payment
2. Retry if VIES is temporarily down
3. Fall back to cached data if needed

A typical flow:

Customer enters VAT number
    -> EuroValidate /v1/vat/{number}
    -> Update price display (with/without VAT)
    -> Customer confirms and pays
    -> Stripe PaymentIntent with correct amount
    -> Store validation proof

VAT rates by country

If reverse charge does not apply and you need the correct VAT rate for the customer's country, use the /v1/vat-rates endpoint:

curl -H "X-API-Key: your_api_key" \
  https://api.eurovalidate.com/v1/vat-rates/FR

{
  "success": true,
  "data": {
    "country_code": "FR",
    "standard_rate": 20.0,
    "reduced_rates": [10.0, 5.5, 2.1],
    "super_reduced_rate": null,
    "parking_rate": null
  }
}

This saves you from hardcoding VAT rates that change (Luxembourg went from 15% to 17% in 2024, for example).

Complete example: Stripe webhook handler

After payment succeeds, store the validation proof:

@app.post("/webhooks/stripe")
async def stripe_webhook(request: Request):
    payload = await request.body()
    sig = request.headers.get("stripe-signature")
    event = stripe.Webhook.construct_event(payload, sig, webhook_secret)

    if event["type"] == "payment_intent.succeeded":
        intent = event["data"]["object"]
        metadata = intent["metadata"]

        if metadata.get("reverse_charge") == "True":
            # Store reverse charge proof
            store_validation_proof(
                payment_intent_id=intent["id"],
                vat_number=metadata["vat_number"],
                vat_valid=metadata["vat_valid"],
                confidence=metadata["vat_confidence"],
                request_id=metadata["validation_request_id"],
            )

    return {"status": "ok"}

Summary

Adding EU VAT validation to Stripe takes three steps:

1. Validate the VAT number with EuroValidate before creating the PaymentIntent
2. Apply reverse charge if the number is valid and the customer is in a different EU country
3. Store the validation proof (result, timestamp, confidence, request ID) for tax audit compliance

The confidence score is the key differentiator. Instead of a binary valid/invalid that breaks when VIES is down, you get a graduated assessment that lets your checkout flow degrade gracefully.

Get a free API key at eurovalidate.com. Full API reference at api.eurovalidate.com/docs.

There are five different government APIs you need to validate European business data. VIES is SOAP. EORI is SOAP. HMRC is REST. GLEIF is REST. IBAN is offline computation. Each has different authentication, different response formats, different failure modes, different country-code conventions, and different ideas about what "available" means.

I built EuroValidate because I got tired of writing the same integration code in every project. This is the story of how it went from "I should just wrap these APIs" to a production system with 30 circuit breakers, 130 bank entries, and a confidence scoring engine -- built solo, from Portugal, on infrastructure that costs less than a coffee per day.

The problem: five APIs, five headaches

Here is what you need to validate EU business data end-to-end:

If you are building a fintech KYB flow, you need at least three of these. If you are building an e-commerce checkout with EU tax compliance, you need four. If you are doing cross-border logistics, you need all five.

Each integration takes 2-4 days to build properly (with error handling, retries, caching). That is 10-20 days of work before you even start on your actual product. And then you maintain five integrations forever.

Why existing solutions did not work

I looked at every competitor I could find. Over 30 of them. The landscape breaks into three categories:

VAT-only tools (Vatstack, Vatchecker, Abstract VAT): They handle VAT validation well but do not touch IBAN, EORI, or company data. You still need three more integrations.

IBAN-only tools (Ibanapi.com, openiban.com): Same problem from the other direction. You get IBAN validation but nothing else.

Expensive unified tools (Surepass, Veriphy): They cover multiple data types but price at enterprise levels. A startup doing 5,000 validations per month does not need a sales call and a custom contract.

The gap was clear: a unified API that covers all five validation types, at a price point that makes sense for indie developers and small SaaS teams, with reliability engineering that accounts for the fact that government APIs go down constantly.

Architecture decisions

Why FastAPI

FastAPI was the obvious choice for three reasons:

1. Async-native: VIES calls take 200-2000ms. If you are handling concurrent requests (and you are, since this is an API), blocking on each SOAP call kills throughput. FastAPI's async support lets us run VIES calls in thread executors without blocking the event loop.

2. Auto-generated OpenAPI 3.1 docs: The API spec is the product. Auto-generated Swagger and Redoc documentation mean the docs are always in sync with the code. No separate doc maintenance.

3. Pydantic v2 for request/response models: Every response model is typed. Every error follows RFC 7807. The schema drives SDK generation. One source of truth.

Per-country circuit breakers

This was the most important architectural decision. VIES routes requests to 27 national backends. Germany goes down frequently. If you use a single circuit breaker for all of VIES, Germany being down trips the breaker and blocks France, Netherlands, and everyone else.

We run 28 independent VIES breakers (one per member state, with GR and EL aliased since they are the same backend). Plus one for EC EORI and one for HMRC UK. Thirty breakers total.

EU_COUNTRY_CODES: list[str] = [
    "AT", "BE", "BG", "CY", "CZ", "DE", "DK", "EE", "EL", "ES",
    "FI", "FR", "GR", "HR", "HU", "IE", "IT", "LT", "LU", "LV",
    "MT", "NL", "PL", "PT", "RO", "SE", "SI", "SK",
]

class CircuitBreakerRegistry:
    def __init__(self):
        self._vies_breakers = {}
        for cc in EU_COUNTRY_CODES:
            self._vies_breakers[cc] = _make_breaker(f"vies_{cc}")
        # Greece: GR and EL are the same backend
        self._vies_breakers["GR"] = self._vies_breakers["EL"]
        self._eori_breaker = _make_breaker("eori_ec")
        self._hmrc_breaker = _make_breaker("hmrc_uk")

Each breaker trips after 5 consecutive failures and probes after 60 seconds. State transitions are logged for observability.

Dual-layer cache

Redis for hot reads (sub-millisecond). PostgreSQL for persistence (survives restarts). The lookup chain:

1. Check Redis (fast path, handles 90%+ of repeat queries)
2. Check PostgreSQL (warm path, catches Redis misses after restart)
3. Call upstream (slow path, only on cache miss)

VAT data is cached for 24 hours. IBAN validation is purely offline, so there is no cache -- it is always instant. GLEIF data is cached for 7 days (it changes rarely). Bank registry data is cached for 30 days (updated monthly from Bundesbank).

Confidence scoring

Every response includes a confidence level. This was inspired by how financial systems handle data quality -- you never just say "valid" or "invalid" without context.

The scoring rules:

• HIGH: Live upstream response, or deterministic offline check (IBAN MOD 97), or cached data under 1 hour old
• MEDIUM: Cached data between 1-24 hours old
• LOW: Cached data over 24 hours old
• UNKNOWN: Upstream unreachable, no cache exists

Cross-referencing can promote MEDIUM to HIGH when two independent sources (e.g., VIES and GLEIF) agree on an entity. But it never promotes LOW or UNKNOWN -- stale is stale regardless of how many stale sources agree.

This is the feature that makes EuroValidate different from a simple wrapper. Clients can build decision trees:

if confidence == HIGH: auto-approve
if confidence == MEDIUM: auto-approve with note
if confidence == LOW: queue for manual review
if confidence == UNKNOWN: reject or retry later

Tech stack and costs

The full stack:

Python 3.12+ / FastAPI (async, auto OpenAPI 3.1)
zeep (VIES + EORI SOAP)
httpx (GLEIF + HMRC async REST)
Redis 7 (hot cache)
PostgreSQL 16 (persistent cache, API keys, usage logs)
pybreaker (circuit breakers)
tenacity (retry with exponential backoff + jitter)
Stripe Billing Meters (usage-based billing)
Hetzner CX22 (hosting)
Cloudflare (CDN, DDoS, SSL)

Monthly cost at launch:

All upstream data sources are free. VIES, EORI, HMRC, GLEIF -- all government or public-interest APIs with no usage fees. The business model is API arbitrage: free government data in, reliable paid API out. The margin is essentially the reliability engineering.

The IBAN validator: 435 lines of offline correctness

The IBAN validator deserves its own mention because it demonstrates a different approach. Unlike VIES (which requires network calls to unreliable SOAP services), IBAN validation is entirely offline and deterministic.

The validator implements:

1. Format normalization: Strip spaces, dashes, uppercase
2. Country-specific length validation: 88 countries supported (from the SWIFT IBAN Registry)
3. MOD 97 check digit verification: ISO 7064 algorithm
4. BBAN extraction: Country-specific parsing rules
5. Bank lookup: BIC and bank name from an in-memory registry of 130 EU banks across 27 countries
6. SEPA reachability: Is this IBAN in the Single Euro Payments Area?

A single function call returns all of this:

result = validate_iban("NL91ABNA0417164300")
# IbanResult(
#   valid=True,
#   country="NL",
#   check_digits="91",
#   bban="ABNA0417164300",
#   bic="ABNANL2AXXX",
#   bank_name="ABN AMRO Bank N.V.",
#   bank_city="Amsterdam",
#   sepa_reachable=True
# )

No network call. No cache. No retry. No circuit breaker. Always HIGH confidence. Response time: effectively zero (CPU computation only).

The bank registry covers all 27 EU member states plus the UK. Each country has 3-6 major clearing banks mapped to their BIC codes. The extraction rules are country-specific -- Germany uses an 8-digit Bankleitzahl, France uses a 5-digit code banque, Netherlands uses 4-letter bank codes, Italy skips the first character (CIN check digit) before extracting the ABI code.

The Greece bug and other war stories

The Greece EL vs GR issue is a rite of passage for anyone integrating with VIES. ISO 3166-1 says Greece is GR. VIES says EL (from Ellada, the Greek name). If you send GR to VIES, you get INVALID_INPUT. If you store EL in your database and join it with anything that uses ISO country codes, your joins break.

We handle this with bidirectional mapping at the boundary:

_COUNTRY_TO_VIES: dict[str, str] = {"GR": "EL"}
_VIES_TO_COUNTRY: dict[str, str] = {"EL": "GR"}

Input gets mapped to VIES format. Output gets mapped back to ISO. The rest of the system only sees GR. This seems trivial until you realize that the circuit breaker registry also needs to alias GR and EL to the same breaker instance, not two separate ones.

Other edge cases we handle:

• Germany and Spain never return company names (national law). We return null instead of empty strings and fall back to GLEIF for company identity.
• Northern Ireland has dual status: XI for EU customs, GB for UK VAT. Different validation systems, different protocols.
• Monaco uses French VAT prefixes (FR). Canary Islands are outside the EU VAT area despite being Spanish territory.
• VIES returns "---" as a literal string when data is unavailable. Three dashes. Not null. Not empty string. Three dashes.

Solo founder: what I would do differently

Ship the landing page first. I built the API before the landing page. I should have put up a landing page with an email capture, validated demand with SEO content about VIES reliability problems, and then built the API. The content marketing pipeline should start before the code.

Start with fewer endpoints. EuroValidate launched with VAT, IBAN, EORI, company lookup, VAT rates, batch processing, monitoring webhooks, and a status endpoint. That is eight endpoints. I should have launched with VAT and IBAN only, gotten paying customers, then expanded. Two endpoints that work perfectly beat eight that are untested in production.

Invest in test data earlier. EU validation has dozens of edge cases (Greece codes, Northern Ireland, territorial exceptions). I should have built a comprehensive test data matrix on day one instead of discovering edge cases during integration testing.

What is next

The roadmap is driven by EU regulatory changes and developer requests:

ViDA compliance (VAT in the Digital Age): The EU is rolling out mandatory e-invoicing and real-time digital reporting. EuroValidate will provide ViDA-ready validation endpoints that check whether a transaction meets the new requirements before you submit it to your tax authority.

GLEIF bulk import: Pre-warming the cache with the entire GLEIF database (~2.5M entities with LEIs). This means company lookups for LEI holders will always be instant, never hitting the upstream API.

Go SDK: Python and Node.js SDKs are generated from the OpenAPI spec. Go is next, followed by PHP. The spec-first approach means SDK generation is mostly automated.

Expanded bank registry: The current 130-bank registry covers the major clearing institutions. We are working on importing the full Bundesbank SCL-Directory (thousands of German banks) and equivalent registries from other countries.

The numbers

As of launch:

• 130 EU banks in the IBAN registry across 27 countries
• 30 circuit breakers (28 VIES + 1 EORI + 1 HMRC)
• 88 countries supported for IBAN length validation
• 38 SEPA countries in the reachability check
• 4 confidence levels with deterministic scoring
• 3 retry attempts with exponential backoff + jitter for transient VIES errors
• 10 concurrent VIES threads (bounded pool to avoid contributing to MS_MAX_CONCURRENT_REQ)
• ~10 EUR/mo infrastructure cost

The business model is straightforward. Free tier at 100 calls/month for testing. Paid tiers from $19/mo (5,000 calls) to $149/mo (100,000 calls). Enterprise above that. Usage-based billing through Stripe Billing Meters.

The gross margin is 95%+ because every upstream data source is free. You are paying for the reliability layer: caching, circuit breakers, confidence scoring, graceful degradation, unified JSON responses, and the engineering time spent handling every VIES edge case so you do not have to.

Try it

EuroValidate is live at eurovalidate.com. API documentation at api.eurovalidate.com/docs. Free tier, no credit card required.

If you have built VIES integrations before, you know the pain. If you have not, you now know what to expect. Either way, you should not have to write another SOAP client in 2026.