Dev.to WebDev πŸ›  Dev πŸ‘ 0 πŸ“– 14 min read

PSD3 and the Payment Services Regulation: Building IBAN-Name Verification and a Fraud-Liability Decision Engine in Spring Boot

Last year a friend almost wired a rental deposit to a fraudster. The invoice looked right, the IBAN was copied from an email, and the bank app accepted it without a murmur. Nothing in the flow asked the one question that

PSD3 and the Payment Services Regulation: Building IBAN-Name Verification and a Fraud-Liability Decision Engine in Spring Boot

Illustration of a payment screen showing a bank transfer with a name check result beside a balance scale weighing a refund claim, representing IBAN-name verification and fraud liability under PSD3

Last year a friend almost wired a rental deposit to a fraudster. The invoice looked right, the IBAN was copied from an email, and the bank app accepted it without a murmur. Nothing in the flow asked the one question that would have saved them: does this account belong to the person I think I'm paying?

That question is now a legal requirement, and the next wave of EU rules also decides who pays when the answer is ignored. I build payment backends for a living, so this post is the version I wish I had when the compromise texts landed: first the plain explanation, then the architecture, then the code.

Part 1: The idea in plain words

Let me define the terms before I use them.

  • IBAN (International Bank Account Number): the long account identifier used for European transfers.
  • PSP (Payment Service Provider): a bank, payment institution or e-money company that moves money for customers.
  • PSD3 (Payment Services Directive 3): the third generation of the EU directive that licenses and supervises payment providers.
  • PSR (Payment Services Regulation): a companion law. A directive has to be converted into national law, while a regulation applies directly. The PSR carries the operational rules that engineers actually feel.
  • VoP (Verification of Payee): the name check. You type a name and an IBAN; the sending bank asks the receiving bank whether they belong together.
  • IPR (Instant Payments Regulation): the 2024 law that already forces euro-area providers to offer VoP on instant euro transfers.
  • APP fraud (Authorised Push Payment fraud): the customer themselves approves the payment, but only because a scammer deceived them. The customer did nothing "unauthorised" in the technical sense, which is why refund rules for it are contested.

Verification of Payee has three possible answers:

  1. Match: the name fits the account holder.
  2. Close match: the name is nearly right, for example a typo or a missing middle name. The receiving bank may reveal the correct name to the payer.
  3. No match: the name does not fit, or the account cannot be verified.

If I only had to explain it to a relative: it is the "are you sure this is the right person?" prompt that a bank is obliged to show, powered by a short conversation between two banks.

The IPR applies this to euro instant payments. According to the Council's published compromise texts from April 2026, the PSR package extends the idea to credit transfers in euro more broadly, and it links fraud liability to how the check was handled. The package was still in its final adoption stage when I wrote this, so please read the official text for the final article wording before you freeze any rule in production.

Part 2: What the law asks the engineer to prove

Two requirements turn into code.

Requirement one: do the check. Before the payer confirms, the system must ask the payee's bank, wait a short time, and present one of the three outcomes clearly.

Requirement two: remember everything. Liability depends on events: was the check offered, was the result shown, did the customer proceed despite a warning? A bank that cannot reconstruct those events months later has no defence in a refund dispute, whatever the law says.

I want to be honest about a gap. Different commentators describe the scope of impersonation-fraud liability differently. Some read it as covering only a scam where the fraudster poses as the customer's bank, others read it more widely. I am not going to pick a reading for you. In my design the liability rules live in configuration, with the text version they were built against recorded next to every decision. That is the only responsible way to build against a moving target.

Here is the shape of the whole system.

Architecture diagram of a Spring Boot payee verification service: payer request, name matcher, call to the payee bank with timeout and fallback, audit trail, then a liability classifier that stores evidence for refund claims

The flow has two halves. The synchronous half sits inside the payment journey and must answer in about a second. The asynchronous half classifies liability later, when a claim arrives, using the evidence the first half stored.

Part 3: The VoP service

Modelling the outcome

I start with types, because the whole design depends on never confusing "no match" with "we could not check". These are different legal facts.

public enum VopOutcome {
    MATCH,
    CLOSE_MATCH,
    NO_MATCH,
    UNAVAILABLE   // we asked and got no usable answer in time
}

public record VopRequest(
        String checkId,
        String payerPspRef,
        String payeeIban,
        String payeeNameAsTyped,
        Instant requestedAt) {}

public record VopResult(
        String checkId,
        VopOutcome outcome,
        String suggestedName,   // only for CLOSE_MATCH, if the payee bank shares it
        int score,              // 0-100, our own similarity score
        String source) {}       // "PAYEE_PSP", "LOCAL_RULE", "TIMEOUT_FALLBACK"

UNAVAILABLE is the type that saves you later. If a payer proceeds after an unavailable check, the liability story is different from proceeding after an explicit no-match.

Fuzzy name matching

Names are messy. "MΓΌller", "Mueller" and "MULLER" are the same person. Company names carry suffixes like "GmbH" or "B.V.". Banks also differ in how they store a name, so I normalise first and compare second.

@Component
public class NameMatcher {

    private static final Set<String> NOISE = Set.of(
            "gmbh", "bv", "b.v.", "ltd", "sa", "sas", "ag", "srl", "mr", "mrs");

    public int score(String typed, String registered) {
        String a = normalise(typed);
        String b = normalise(registered);
        if (a.isEmpty() || b.isEmpty()) return 0;
        if (a.equals(b)) return 100;

        int tokenScore = tokenOverlap(a, b);
        int editScore = editSimilarity(a, b);
        return Math.max(tokenScore, editScore);
    }

    String normalise(String raw) {
        String folded = Normalizer.normalize(raw, Normalizer.Form.NFKD)
                .replaceAll("\\p{M}", "")
                .replace("ß", "ss")
                .replace("ue", "u")
                .toLowerCase(Locale.ROOT)
                .replaceAll("[^a-z0-9 ]", " ");
        return Arrays.stream(folded.split("\\s+"))
                .filter(t -> !t.isBlank() && !NOISE.contains(t))
                .sorted()                       // order-insensitive: "Anna Meyer" == "Meyer Anna"
                .collect(Collectors.joining(" "));
    }

    private int tokenOverlap(String a, String b) {
        Set<String> sa = Set.of(a.split(" "));
        Set<String> sb = Set.of(b.split(" "));
        long common = sa.stream().filter(sb::contains).count();
        return (int) Math.round(100.0 * common / Math.max(sa.size(), sb.size()));
    }

    private int editSimilarity(String a, String b) {
        int dist = levenshtein(a, b);
        int longest = Math.max(a.length(), b.length());
        return (int) Math.round(100.0 * (longest - dist) / longest);
    }

    private int levenshtein(String s, String t) {
        int[] prev = new int[t.length() + 1];
        int[] curr = new int[t.length() + 1];
        for (int j = 0; j <= t.length(); j++) prev[j] = j;
        for (int i = 1; i <= s.length(); i++) {
            curr[0] = i;
            for (int j = 1; j <= t.length(); j++) {
                int cost = s.charAt(i - 1) == t.charAt(j - 1) ? 0 : 1;
                curr[j] = Math.min(Math.min(curr[j - 1] + 1, prev[j] + 1), prev[j - 1] + cost);
            }
            var tmp = prev; prev = curr; curr = tmp;
        }
        return prev[t.length()];
    }
}

Two cautions from experience. First, the sort-the-tokens trick makes "Anna Meyer" and "Meyer Anna" identical, which is correct for payee checks but would be wrong for a fraud model that cares about order. Second, thresholds are policy, not maths. In real deployments the payee bank usually does the matching against its own records, so my matcher is mostly for the case where I am the receiving side, or where I post-process a vague answer. The thresholds below are therefore configuration.

vop:
  thresholds:
    match-min: 95
    close-match-min: 70
  timeout:
    payee-psp-ms: 900
    max-retries: 0
  fallback:
    on-timeout: UNAVAILABLE
    allow-proceed-on-unavailable: true
  liability-ruleset: "psr-compromise-2026-04-config-v1"

Timeout and fallback policy

An instant payment has a tight budget. If the receiving bank is slow, the payer is staring at a spinner while the clock runs. I give the remote call a hard deadline, no retries inside the payment journey, and an explicit fallback. This is the same discipline I describe in my post on idempotent payment pipelines with the transactional outbox: in payments, every timeout path must be a designed path.

@Service
public class VopService {

    private final PayeePspClient client;
    private final NameMatcher matcher;
    private final VopAuditLog audit;
    private final VopProperties props;

    public VopService(PayeePspClient client, NameMatcher matcher,
                      VopAuditLog audit, VopProperties props) {
        this.client = client; this.matcher = matcher;
        this.audit = audit; this.props = props;
    }

    public VopResult verify(VopRequest req) {
        VopResult result;
        try {
            var reply = CompletableFuture
                    .supplyAsync(() -> client.lookup(req.payeeIban()),
                            Executors.newVirtualThreadPerTaskExecutor())
                    .orTimeout(props.timeout().payeePspMs(), TimeUnit.MILLISECONDS)
                    .join();
            result = classify(req, reply);
        } catch (CompletionException ex) {
            result = new VopResult(req.checkId(), VopOutcome.UNAVAILABLE,
                    null, 0, "TIMEOUT_FALLBACK");
        }
        audit.recordCheck(req, result);   // always, before returning anything to the payer
        return result;
    }

    private VopResult classify(VopRequest req, PayeeReply reply) {
        if (!reply.accountFound()) {
            return new VopResult(req.checkId(), VopOutcome.NO_MATCH, null, 0, "PAYEE_PSP");
        }
        int score = matcher.score(req.payeeNameAsTyped(), reply.registeredName());
        var t = props.thresholds();
        if (score >= t.matchMin()) {
            return new VopResult(req.checkId(), VopOutcome.MATCH, null, score, "PAYEE_PSP");
        }
        if (score >= t.closeMatchMin()) {
            String hint = reply.mayDisclose() ? reply.registeredName() : null;
            return new VopResult(req.checkId(), VopOutcome.CLOSE_MATCH, hint, score, "PAYEE_PSP");
        }
        return new VopResult(req.checkId(), VopOutcome.NO_MATCH, null, score, "PAYEE_PSP");
    }
}

I use virtual threads here because the call is pure waiting on network I/O. If you want the production background, my write-up on Java virtual threads in Spring Boot covers pinning and pool behaviour. In a real build I would create the executor once as a bean rather than per call; I inlined it to keep the example short.

Notice the ordering: the audit record is written before the method returns. If the audit write fails, the payment journey should fail closed or degrade to a documented manual path. A check that happened but left no trace is worth nothing in a dispute.

Part 4: An immutable audit trail

"Immutable" is a strong word, so let me be precise. I mean append-only at the application level, tamper-evident through hash chaining, and protected at the database level with permissions that deny updates and deletes.

Each event captures one fact. The facts I record per payment attempt are:

  1. The check was offered (the payer was given the chance).
  2. The result was displayed (with the exact wording version shown).
  3. The payer acted: confirmed, edited the name, or cancelled.
  4. For a warning, the payer overrode it, explicitly.
public record AuditEvent(
        UUID eventId,
        String checkId,
        String type,          // CHECK_OFFERED, RESULT_SHOWN, PAYER_CONFIRMED, MISMATCH_OVERRIDDEN ...
        String payloadJson,
        String uiTextVersion, // which warning copy the customer saw
        Instant occurredAt,
        String prevHash,
        String hash) {}

@Repository
public class VopAuditLog {

    private final JdbcTemplate jdbc;
    private final ObjectMapper mapper;

    public VopAuditLog(JdbcTemplate jdbc, ObjectMapper mapper) {
        this.jdbc = jdbc; this.mapper = mapper;
    }

    @Transactional
    public AuditEvent append(String checkId, String type, Object payload, String uiTextVersion) {
        String prev = jdbc.query(
                "select hash from vop_audit where check_id = ? order by seq desc limit 1",
                rs -> rs.next() ? rs.getString(1) : "GENESIS", checkId);
        String json = toJson(payload);
        Instant now = Instant.now();
        String hash = sha256(prev + type + json + uiTextVersion + now);
        var event = new AuditEvent(UUID.randomUUID(), checkId, type, json,
                uiTextVersion, now, prev, hash);
        jdbc.update("""
            insert into vop_audit(event_id, check_id, type, payload, ui_text_version,
                                  occurred_at, prev_hash, hash)
            values (?,?,?,?::jsonb,?,?,?,?)""",
            event.eventId(), checkId, type, json, uiTextVersion,
            Timestamp.from(now), prev, hash);
        return event;
    }

    public void recordCheck(VopRequest req, VopResult res) {
        append(req.checkId(), "CHECK_PERFORMED", res, "n/a");
    }

    private String toJson(Object o) {
        try { return mapper.writeValueAsString(o); }
        catch (JsonProcessingException e) { throw new IllegalStateException(e); }
    }

    private String sha256(String s) {
        try {
            var d = MessageDigest.getInstance("SHA-256").digest(s.getBytes(StandardCharsets.UTF_8));
            return HexFormat.of().formatHex(d);
        } catch (NoSuchAlgorithmException e) { throw new IllegalStateException(e); }
    }
}

Hash chaining per check means an auditor can recompute the chain and spot a deleted or edited row. Pair it with a database role that only has INSERT and SELECT on the table. Concurrent appends for the same check are rare, but add a unique constraint on (check_id, prev_hash) so a fork fails loudly instead of silently.

Storing uiTextVersion matters more than it looks. When a customer says "your app never warned me", the strongest answer is the exact copy, the exact version, and the timestamp of the screen that carried it. If you run feature flags on warning text, version those strings like code. I took the same stance with compliance artefacts in my DORA and NIS2 policy-as-code post: evidence you generate at runtime beats evidence you reconstruct during an audit.

Part 5: The fraud-liability classifier

Now the part that makes finance teams lean forward. When a customer claims a refund after a scam, someone has to decide whether the PSP refunds, pushes back, or shares the loss with the payee's PSP. The compromise text ties that to the payee-check handling. My engine does not decide law. It reads the evidence and applies a ruleset that compliance owns.

The inputs I feed the classifier:

Evidence Where it comes from
Was the check offered? CHECK_OFFERED event
What was the outcome? CHECK_PERFORMED payload
Was it shown to the payer? RESULT_SHOWN event plus UI text version
Did the payer override a warning? MISMATCH_OVERRIDDEN event
Claimed fraud type Claims intake form

Rules are data, not code. A small interface keeps them swappable, and the active ruleset id is stamped on every verdict.

public enum Verdict { REFUND_PSP, CONTEST_PAYER_LIABLE, SHARE_WITH_PAYEE_PSP, MANUAL_REVIEW }

public record Evidence(
        boolean checkOffered,
        VopOutcome outcome,
        boolean resultShown,
        boolean warningOverridden,
        FraudType claimedType,
        List<UUID> supportingEventIds) {}

public record Decision(Verdict verdict, String ruleId, String rulesetVersion,
                       String rationale, List<UUID> evidence) {}

public interface LiabilityRule {
    String id();
    boolean appliesTo(FraudType type);               // keeps scope configurable
    Optional<Verdict> evaluate(Evidence e);
}

@Component
public class LiabilityEngine {

    private final List<LiabilityRule> rules;
    private final VopProperties props;

    public LiabilityEngine(List<LiabilityRule> rules, VopProperties props) {
        this.rules = rules; this.props = props;
    }

    public Decision decide(Evidence e) {
        for (LiabilityRule rule : rules) {
            if (!rule.appliesTo(e.claimedType())) continue;
            var v = rule.evaluate(e);
            if (v.isPresent()) {
                return new Decision(v.get(), rule.id(), props.liabilityRuleset(),
                        explain(rule, e), e.supportingEventIds());
            }
        }
        return new Decision(Verdict.MANUAL_REVIEW, "NO_RULE_MATCHED",
                props.liabilityRuleset(), "No configured rule covered this evidence.",
                e.supportingEventIds());
    }

    private String explain(LiabilityRule r, Evidence e) {
        return "Rule %s fired: offered=%s outcome=%s shown=%s overridden=%s"
                .formatted(r.id(), e.checkOffered(), e.outcome(),
                        e.resultShown(), e.warningOverridden());
    }
}

Here are two example rules. They illustrate the mechanism; the verdicts they return are a reading, not a statement of what the regulation says.

@Component
@ConditionalOnProperty(name = "liability.rules.check-not-offered.enabled", havingValue = "true")
class CheckNotOfferedRule implements LiabilityRule {
    public String id() { return "CHECK_NOT_OFFERED"; }
    public boolean appliesTo(FraudType t) { return t == FraudType.IMPERSONATION; }
    public Optional<Verdict> evaluate(Evidence e) {
        // If the PSP never offered the check, defending a refusal is hard.
        return e.checkOffered() ? Optional.empty() : Optional.of(Verdict.REFUND_PSP);
    }
}

@Component
@ConditionalOnProperty(name = "liability.rules.warning-overridden.enabled", havingValue = "true")
class WarningOverriddenRule implements LiabilityRule {
    public String id() { return "WARNING_OVERRIDDEN"; }
    public boolean appliesTo(FraudType t) { return t == FraudType.IMPERSONATION; }
    public Optional<Verdict> evaluate(Evidence e) {
        boolean warned = e.outcome() == VopOutcome.NO_MATCH || e.outcome() == VopOutcome.CLOSE_MATCH;
        if (e.checkOffered() && e.resultShown() && warned && e.warningOverridden()) {
            return Optional.of(Verdict.MANUAL_REVIEW); // flag for a human; do not auto-deny
        }
        return Optional.empty();
    }
}

Two design choices deserve explanation.

Overridden warnings go to manual review, not automatic denial. The sources I read disagree on how far a customer's override should cut the refund right, and a wrong automated denial in a consumer-protection area is expensive. If your legal team settles on a firm reading, flip the rule through configuration and bump the ruleset version.

The appliesTo hook carries the scope argument. If the final reading covers only bank-impersonation scams, you narrow the FraudType list in configuration. If it covers wider impersonation, you widen it. The code paths stay the same, and historical decisions remain explainable because each carries the ruleset version that produced it.

Defending or conceding a claim

When the engine returns a verdict, I generate an evidence bundle: the ordered audit events, the hash chain proof, the UI copy shown, and the rule rationale. If the verdict is to concede, the same bundle supports the recovery claim against the payee's PSP. It is far better to concede quickly with clean records than to fight with half a file.

Part 6: Operational lessons from running payment systems

I have worked on high-traffic systems (AirAsia's booking platform handled around 130 million requests a day) and on open banking APIs, and the lessons repeat. Some I would apply here:

  • Measure the check as its own service. Track p95 latency and the share of UNAVAILABLE results per counterparty bank. A single weak partner can quietly push your unavailable rate up. The tracing setup from my distributed tracing guide works well here: one trace id from the payer tap through the VoP call to the audit write.
  • Treat the UI as part of the compliance system. The best backend cannot prove a warning was shown if the front end never reports it. Make the RESULT_SHOWN event a server-confirmed acknowledgement, not a fire-and-forget log.
  • Replay your rules. Keep a corpus of anonymised past claims and run every ruleset change against it before release. This is the same idea as deterministic replay I use for market data, described in my market-data replay article.
  • Keep personal data narrow. Names and IBANs are personal data. Retention periods for audit rows should be decided with your data-protection officer, and the hash chain can outlive payload deletion if you hash a salted payload digest rather than the clear text.

If you have read my notes on Open Banking PSD2 API development, this will feel familiar: the previous generation asked you to expose and secure APIs, and this one asks you to prove, afterwards, what each customer was told.

What I would not hard-code

After building this, here is my short list of things that should stay configurable:

  1. Match and close-match thresholds.
  2. Timeout length and the fallback behaviour on UNAVAILABLE.
  3. Which fraud types each liability rule covers.
  4. The verdict for an overridden warning.
  5. The ruleset id and the text version it was derived from.

Everything else, such as the three outcomes, the append-only audit and the evidence bundle, is stable under any reading of the text I have seen.

Your next step

Pick one live transfer journey in your system, add a CHECK_OFFERED and a RESULT_SHOWN audit event to it this week, and stamp each with the UI text version. That single change gives your compliance team real evidence to work with, whichever way the final liability wording lands. If you want help designing this for your payment stack, reach out through my contact section, see the payment systems I have shipped in my experience, or browse my projects.

Related Articles

πŸ“° Read the original article on Dev.to WebDev

Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes β€” full credit and traffic to the original publisher.