Verification of Payee API documentation
Authentication, the verify endpoint, request and response payloads, SEPA scheme match codes and error handling — everything a developer needs to integrate the IBAN/name check, with copy-paste JSON and cURL examples.
{BASE_URL}/vop/v1/verify - Auth
- Bearer token (OAuth 2.0)
- Format
- application/json
Base URL and API credentials are provided when you onboard — talk to us to get them.
The Verification of Payee API is a single authenticated REST endpoint: you POST a payee name and IBAN and receive a standardised match outcome in real time. The examples below are illustrative; your exact base URL and credentials are issued during onboarding.
Authentication
Every request is authenticated with a bearer token over HTTPS. Send the token in the Authorization header; tokens are issued per environment (sandbox and production).
The same credentials also unlock the RoxBusiness dashboard, where you can run ad-hoc verifications without writing code.
Authorization: Bearer <YOUR_API_TOKEN>
Content-Type: application/jsonRequest
POST a JSON body with the payee name and IBAN. For legal persons you may also send an organisation identifier (e.g. an Italian Partita IVA / Codice Fiscale), and an optional external_id for reconciliation.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Required | Payee name to verify, as the payer entered it. |
| iban | string | Required | Destination IBAN (validated for format and checksum before the scheme call). |
| account_type | enum | Optional | NATURAL_PERSON or LEGAL_PERSON. Helps the responding bank match correctly. |
| organisation_id | string | Optional | VAT number / tax code for legal persons (e.g. Partita IVA). Verified against the registered holder. |
| external_id | string | Optional | Your own reference id, echoed back in the response for reconciliation. |
{
"name": "ACME Trading S.r.l.",
"iban": "IT60X0542811101000000123456",
"account_type": "LEGAL_PERSON",
"organisation_id": "IT01524770524",
"external_id": "invoice-2025-00842"
}curl -X POST "$BASE_URL/vop/v1/verify" \
-H "Authorization: Bearer $ROXPAY_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "ACME Trading S.r.l.",
"iban": "IT60X0542811101000000123456",
"account_type": "LEGAL_PERSON",
"organisation_id": "IT01524770524",
"external_id": "invoice-2025-00842"
}'Response
A 200 response returns the normalised result, the SEPA scheme match code, the responding bank BIC and the processing time. On a close match the verified name is returned as suggested_name.
Response body
| Field | Type | Description |
|---|---|---|
| verification_id | string | Unique id for this verification, for your audit trail. |
| result | enum | MATCH, CLOSE_MATCH, NO_MATCH or NOT_APPLICABLE. |
| scheme_code | string | The SEPA VoP scheme code: MTCH, CMTC, NMTC or NOAP. |
| suggested_name | string | On CLOSE_MATCH, the verified account-holder name to suggest to the payer. |
| responding_bic | string | BIC of the institution that answered the verification. |
| processing_time_ms | integer | Time the responding PSP took, in milliseconds. |
| external_id | string | Your reference id, echoed back unchanged. |
{
"verification_id": "vop_3f9a1c2e7b",
"result": "CLOSE_MATCH",
"scheme_code": "CMTC",
"suggested_name": "ACME Trading SRL",
"responding_bic": "BCITITMMXXX",
"processing_time_ms": 412,
"external_id": "invoice-2025-00842"
}Match outcome codes
Every response maps to one of four SEPA VoP scheme codes. Branch on scheme_code so your logic stays stable.
| Code | Result | Meaning | Recommended action |
|---|---|---|---|
| MTCH | MATCH | Name matches the account holder. | Proceed with confidence. |
| CMTC | CLOSE_MATCH | Almost right (e.g. trading vs legal name). | Show suggested_name; ask the payer to confirm. |
| NMTC | NO_MATCH | Name does not belong to the IBAN. | Hard stop — warn and block auto-approval. |
| NOAP | NOT_APPLICABLE | Verification could not be completed. | Inform the payer; let them decide. |
Error handling
NO_MATCH is a valid 200 result, not an error — never treat it as a transport failure. Genuine errors use 4xx/5xx status codes with a machine-readable error code and a request_id for support.
| HTTP | Error code | When it happens |
|---|---|---|
| 400 | invalid_iban | The IBAN failed format or checksum validation. |
| 400 | missing_field | A required field (name or iban) is absent. |
| 401 | unauthorized | Missing or invalid bearer token. |
| 429 | rate_limited | Too many requests — back off and retry. |
| 503 | scheme_unavailable | The VoP scheme/responding PSP is temporarily unreachable. |
{
"error": "invalid_iban",
"message": "The 'iban' field failed checksum validation.",
"request_id": "req_8a2b1f0c"
}Integrate in four steps
A standard REST integration that drops into your existing payment flow.
- 1
Get credentials
Onboard and receive your bearer token and base URL for sandbox and production.
- 2
Call /verify
POST the payee name and IBAN, with an optional external_id and organisation_id.
- 3
Read scheme_code
Branch on MTCH / CMTC / NMTC / NOAP and store the verification_id.
- 4
Act in your UI
Show a clear signal to the payer, or gate a payment run or mandate on the result.
Developer FAQ
The questions integration teams ask first.
A JSON body with name and iban (required), plus optional account_type, organisation_id (VAT/tax code for legal persons) and your external_id. See the request example above.
NO_MATCH (scheme code NMTC) is a valid 200 response, not an error. Treat it as a hard stop: warn the payer, block auto-approval, and require a re-check before sending.
Yes. Tokens are issued per environment, so you can integrate and test against sandbox before switching the base URL to production.
Yes — send organisation_id with account_type LEGAL_PERSON. This helps when the trading name differs from the registered name.
Send your own external_id in the request; it is echoed back unchanged, and every response also carries a unique verification_id.
Get your API credentials
Onboard to the SEPA VoP scheme with one REST integration and go live before your deadline.