Developer 6 min read

Verification of Payee API Response and Error Codes, Explained

Integration teams rarely struggle with calling a Verification of Payee endpoint — they struggle with interpreting what comes back. Here is how to read every scheme code and, crucially, how to tell a result from an error.

By Verification of Payee EU · powered by RoxPay

Key takeaways

  • The four scheme codes are MTCH (match), CMTC (close match), NMTC (no match) and NOAP (not applicable).
  • NO_MATCH is a valid result, not a transport error — branch on it, don't throw on it.
  • Real errors (invalid IBAN, auth, rate limit) use HTTP 4xx/5xx with a machine-readable code.

The single most common integration bug with Verification of Payee is treating a NO_MATCH as a failed request. It isn't. A successful verification that happens to say 'this name does not belong to this IBAN' is still a 200 response with useful data. Confuse the two and you'll either swallow fraud signals or show users scary errors.

The four scheme codes

Every Verification of Payee response maps to one of four standardised SEPA scheme codes. Branch on the code, not on free-text:

  • MTCH — MATCH: the name matches the account holder. Proceed.
  • CMTC — CLOSE_MATCH: almost right (missing middle name, trading vs legal name). Show the suggested verified name and ask the payer to confirm.
  • NMTC — NO_MATCH: the name does not belong to the IBAN. Warn clearly and block auto-approval.
  • NOAP — NOT_APPLICABLE: the check couldn't be completed (e.g. responding bank unreachable). Let the user decide with extra caution.

Result vs error

If the HTTP status is 200, you have a verification result — read scheme_code. If it's 4xx/5xx, you have an error — read the error code. Never map NO_MATCH onto your error path.

Handling CLOSE_MATCH well

CLOSE_MATCH is where good UX is won or lost. The response can carry the verified account-holder name; surface it as a suggestion ('Did you mean…?') so the payer confirms or corrects rather than abandoning the payment. Treating CMTC as a hard failure frustrates legitimate users.

Genuine error codes

Separate from scheme outcomes, transport-level problems return standard HTTP errors — for example invalid_iban (400), unauthorized (401), rate_limited (429) and scheme_unavailable (503). Each carries a request id so support can trace it. Pass a stable external id on every call so retries stay idempotent and logs reconcile.

All articles
FAQ

Frequently asked

It means the name is almost right — a missing middle name, or a trading name vs a registered name. The response can include the verified name as suggested_name, so you can prompt the payer to confirm instead of rejecting the payment.

NO_MATCH (NMTC) is not an error — it's a valid 200 result. Treat it as a hard stop in your UI or payment run: warn the user, block auto-approval and require a re-check before sending.

Real errors use HTTP 4xx/5xx status codes with a machine-readable error code (e.g. invalid_iban, unauthorized, rate_limited). A no match is a 200 response whose scheme_code is NMTC.

Keep reading

API documentation Endpoint, payloads, codes and examples. Match, close match, no match The same outcomes, for non-developers.

Build VoP into your product

Get your credentials and the full API reference, with sandbox access for testing every code path.

Talk to an expert Read the API docs