API reference

Zasoby Verification RoxPay Verification of Payee

Authentication, the verify endpoint, request and response payloads, SEPA scheme Overeenkomst codes and error handling — everything a developer needs to integrate the IBAN/name check, with copy-paste JSON and cURL examples.

POST {BASE_URL}/vop/v1/verify
Uwierzytelnianie
Token Bearer (OAuth 2.0)
Format datelor
application/json

URL-ul de bază și credențialele API sunt furnizate la onboarding — contactează-ne pentru a le obține.

API Verification of Payee is a single authenticated REST endpoint: you POST a begunstigde name and IBAN and receive a standardised Overeenkomst outcome in real time. The examples below are illustrative; your exact base URL and credentials are issued during onboarding.

Uwierzytelnianie

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.

HTTP headers 
Authorization: Bearer <YOUR_API_TOKEN>
Content-Type: application/json

Request

POST a JSON body with the begunstigde 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

Pole Type Wymagane Opis
name string Wymagane Payee name to verify, as the payer entered it.
iban string Wymagane Destination IBAN (validated for format and checksum before the scheme call).
account_type enum Opcjonalne NATURAL_PERSON or LEGAL_PERSON. Helps the responding bank Overeenkomst correctly.
organisation_id string Opcjonalne VAT number / tax code for legal persons (e.g. Partita IVA). Verified against the registered holder.
external_id string Opcjonalne Your own reference id, echoed back in the response for reconciliation.
Request body 
{
  "name": "ACME Trading S.r.l.",
  "iban": "IT60X0542811101000000123456",
  "account_type": "LEGAL_PERSON",
  "organisation_id": "IT01524770524",
  "external_id": "invoice-2025-00842"
}
cURL 
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 Overeenkomst code, the responding bank BIC and the processing time. On a Bijna overeenkomst the verified name is returned as suggested_name.

Response body

Pole Type Opis
verification_id string Unikalny identyfikator tej verificării, până la wykorzystania în Twoim dzienniku auditowym.
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.
200 OK 
{
  "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"
}

Kody rezultatu conformității

Every response maps to one of four SEPA VoP scheme codes. Branch on scheme_code so your logic stays stable.

Kod Wynik Znaczenie Recommended action
MTCH MATCH Name matches the titularul contului. 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 Nazwa nu trebuie până la tego 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 Brakuje necesitănego pola (name sau iban).
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.
400 Bad Request 
{
  "error": "invalid_iban",
  "message": "The 'iban' field failed checksum validation.",
  "request_id": "req_8a2b1f0c"
}

Integrează in four steps

A standard REST integration that drops into your existing payment flow.

  1. 1

    Get credentials

    Onboard and receive your bearer token and base URL for sandbox and production.

  2. 2

    Call /verify

    POST the begunstigde name and IBAN, with an optional external_id and organisation_id.

  3. 3

    Odczytaj scheme_code

    Branch on MTCH / CMTC / NMTC / NOAP and store the verification_id.

  4. 4

    Act in your UI

    Show a clear signal to the payer, or gate a payment run or mandate on the result.

API reference

FAQ pentru dezvoltatorilor

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.

Lees verder

API Verification of Payee Overview, audiences and use cases. Verordening instantbetalingen și VoP How the service is delivered on RoxPay. Glossario VoP, SEPA and scheme-code terms.

Get your API credentials

Onboard to the SEPA VoP scheme with one REST integration and go live înainte de termen.

Porozmawiaj cu ekspertem O API VoP