Verification of Payee
Does this name belong to this IBAN? Checked at the account-holding bank before a payment is sent, with optional company-ID matching
Universe: Umbrella
Status: beta
Credentials on request. Try it on the mock.
What it answers
Given an account identifier (IBAN or another supported identifier) and an account holder name, Verification of Payee answers one question: does this name belong to this account? It is checked against the account holder records of the connected bank before a payment is sent. Company identifiers can be checked in addition to, or instead of, the name.
Verification of Payee needs no action from the account holder. To confirm that the person in front of you controls the account, use AIS Ident.
Result categories
nameMatchResult carries the outcome:
| Value | Meaning |
|---|---|
MATCH | The name matches the account holder record. |
CLOSE_MATCH | Close but not exact; nameSuggestion carries the suggested correct name. |
NO_MATCH | The name does not match the account holder record. |
COULD_NOT_MATCH | The check could not be completed (for example, the bank does not support matching). |
NAME_TOO_SHORT | The supplied name was too short to match reliably. |
dataUsedForMatching says whether that result came from data VERIFIED at the bank or DERIVED
from historical transactions. The account object separately reports whether the identifier itself is
VALID or NOT_VALID and the account status (ACTIVE, INACTIVE, UNKNOWN, NOT_SUPPORTED,
NOT_FOUND).
One call
Base URLs are in Environments. Authenticate, then call POST /account/check:
curl -X POST "$UMBRELLA_BASE_URL/auth" \
-H "Api-Key: $UMBRELLA_API_KEY" \
-H "Customer-Id: $UMBRELLA_CUSTOMER_ID" \
-H "Content-Type: application/x-www-form-urlencoded"curl -X POST "$UMBRELLA_BASE_URL/account/check" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"accountId": { "type": "IBAN", "value": "NL87MOYO9876543212" },
"name": "John Paul Waldo"
}'Errors
| Status | Meaning |
|---|---|
400 | Bad request: a required field is missing, or the bank-side check rejected the request body. |
401 | The Umbrella bearer token is missing or invalid. |
403 | The authenticated customer does not have access to this product. |
422 | The request body failed field validation. |
429 | Too many requests. |
502 | The bank-side check is not reachable with our credentials; not caused by your request. |
503 | The bank-side check returned a server error or timed out. Retry later. |
All error responses use the same shape: {"status": false, "error": "<message>"}.
Try it
In the Umbrella API reference, choose the
server Mock. POST /account/check answers MATCH; add ?scenario=close-match for a CLOSE_MATCH
with a name suggestion.