If you’re building a fintech app, a payments feature, or anything that moves money between users in Europe, you’ve probably run into a new requirement popping up in bank documentation and compliance checklists: name-matching before a transfer completes. For developers used to treating payments as “just an API call to move money,” this adds a new step that’s worth understanding properly before you start integrating it.
This guide walks through what the integration actually looks like at a technical level, what to test before going live, and a few gotchas that trip up teams building this for the first time.
What You’re Actually Building
At a high level, the flow is simple: before your app confirms a transfer, it sends the payee’s IBAN and name to a verification service, which checks that name against the registered account holder and returns a match status. Your app then decides what to show the user based on that response — proceed normally, show a warning, or block the transfer entirely depending on your risk tolerance.
A simplified version of the request and response typically looks something like this (exact fields vary by provider):
POST /verify-payee
{ “iban”: “NL91ABNA0417164300”, “name”: “J. Smit” }
Response:
{ “match”: “partial”, “registeredName”: “J. Smith” }
The three typical match statuses — full match, partial match, and no match — each need different handling in your UI. A full match usually needs no extra friction. A partial or no match should trigger a clear, human-readable warning rather than a cryptic error code.
Before you start integrating, it’s worth reading a full breakdown of the regulatory background behind any verification of payee API you’re evaluating, since the EU requirements behind this feature explain a lot of the design decisions — like why match statuses are categorical rather than binary, and why audit logging isn’t optional.
Integration Steps
Step 1: Choose whether to build the matching logic in-house or integrate a third-party verification provider — most teams outside large banks choose the latter, since the underlying fuzzy-matching logic is more complex than it first appears.
Step 2: Request sandbox access and test against realistic edge cases: trading names, joint accounts, recently updated account holders, and common transliteration differences for non-Latin scripts.
Step 3: Design your UI states for all three match outcomes — don’t just handle ‘match’ and ‘no match’ as a binary; partial matches need their own clear messaging.
Step 4: Log every check result for audit purposes, including what was shown to the user and what action they took — regulators expect this trail to exist.
Step 5: Add a manual override path so users can proceed after independently verifying a payee, rather than getting permanently blocked by a false positive.
Common Gotchas
Teams integrating this for the first time tend to run into the same handful of issues. Response times matter more than expected — since instant payments settle in seconds, a slow verification call becomes the bottleneck in your entire transfer flow, so latency testing under realistic load is essential, not optional.
Character encoding is another common trap: names with accented characters, non-Latin scripts, or unusual formatting can produce false mismatches if your matching logic (or your provider’s) doesn’t normalise text properly before comparing. Test with a genuinely diverse set of names, not just ASCII examples, before assuming your integration is solid.
Finally, don’t underestimate the UI/UX side. A cryptic “Error: NAME_MISMATCH” is far less useful — and far more alarming — than a plain-language message explaining what happened and what the user can do next. This single design choice has a bigger impact on support ticket volume than most teams expect.
Testing Before Launch
Before going live, run through a checklist covering at least: full-match happy path, partial-match warning display, no-match blocking behaviour, manual override flow, response time under load, and audit log completeness. It’s also worth simulating provider downtime — decide in advance whether your app fails open (allows payments without verification) or fails closed (blocks payments until the check succeeds), since this decision has real compliance implications.
The Takeaway for Developers
Integrating payee verification isn’t just a compliance checkbox — done well, it’s a genuine improvement to how safely your users move money. Treat it as a first-class part of your payment flow rather than a bolt-on afterthought, test the edge cases thoroughly, and make sure your UI actually communicates what’s happening rather than hiding it behind a technical error message. Get those pieces right, and the integration becomes a real trust signal for your users, not just another regulatory hurdle to clear.
