Riferimento API

Documentazione API Verification of Payee

Autenticazione, endpoint di verifica, payload di richiesta e risposta, codici di esito dello schema SEPA e gestione errori — tutto ciò che serve a uno sviluppatore per integrare la verifica IBAN/nome, con esempi JSON e cURL pronti da copiare.

POST {BASE_URL}/vop/v1/verify
Autenticazione
Bearer token (OAuth 2.0)
Formato
application/json

La base URL e le credenziali API vengono fornite all'onboarding — contattaci per ottenerle.

L'API Verification of Payee è un unico endpoint REST autenticato: invii in POST il nome del beneficiario e un IBAN e ricevi un esito standardizzato in tempo reale. Gli esempi qui sotto sono illustrativi; la base URL e le credenziali esatte vengono rilasciate in fase di onboarding.

Autenticazione

Ogni richiesta è autenticata con un bearer token su HTTPS. Invia il token nell'header Authorization; i token sono rilasciati per ambiente (sandbox e produzione).

Le stesse credenziali abilitano anche la dashboard RoxBusiness, dove puoi eseguire verifiche estemporanee senza scrivere codice.

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

Richiesta

Invia in POST un body JSON con il nome del beneficiario e l'IBAN. Per le persone giuridiche puoi inviare anche un identificativo dell'organizzazione (es. Partita IVA / Codice Fiscale) e un external_id opzionale per la riconciliazione.

Corpo della richiesta

Campo Tipo Obbligatorio Descrizione
name string Obbligatorio Nome del beneficiario da verificare, così come inserito da chi paga.
iban string Obbligatorio IBAN di destinazione (validato per formato e checksum prima della chiamata allo schema).
account_type enum Opzionale NATURAL_PERSON o LEGAL_PERSON. Aiuta la banca rispondente a confrontare correttamente.
organisation_id string Opzionale Partita IVA / Codice Fiscale per le persone giuridiche. Verificato rispetto al titolare registrato.
external_id string Opzionale Il tuo id di riferimento, restituito nella risposta per la riconciliazione.
Corpo della richiesta 
{
  "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"
  }'

Risposta

Una risposta 200 restituisce l'esito normalizzato, il codice di corrispondenza dello schema SEPA, il BIC della banca rispondente e il tempo di elaborazione. In caso di corrispondenza parziale il nome verificato è restituito in suggested_name.

Corpo della risposta

Campo Tipo Descrizione
verification_id string Id univoco di questa verifica, per il tuo audit trail.
result enum MATCH, CLOSE_MATCH, NO_MATCH o NOT_APPLICABLE.
scheme_code string Il codice dello schema SEPA VoP: MTCH, CMTC, NMTC o NOAP.
suggested_name string In caso di CLOSE_MATCH, il nome verificato del titolare da suggerire a chi paga.
responding_bic string BIC dell'istituto che ha risposto alla verifica.
processing_time_ms integer Tempo impiegato dal PSP rispondente, in millisecondi.
external_id string Il tuo id di riferimento, restituito invariato.
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"
}

Codici di esito

Ogni risposta corrisponde a uno dei quattro codici dello schema SEPA VoP. Ramifica su scheme_code così la tua logica resta stabile.

Codice Esito Significato Azione consigliata
MTCH MATCH Il nome corrisponde al titolare. Procedi con sicurezza.
CMTC CLOSE_MATCH Quasi esatto (es. nome commerciale vs ragione sociale). Mostra suggested_name; chiedi conferma a chi paga.
NMTC NO_MATCH Il nome non appartiene all'IBAN. Stop deciso — avvisa e blocca l'approvazione automatica.
NOAP NOT_APPLICABLE Verifica non completabile. Informa chi paga; lascia decidere.

Gestione errori

NO_MATCH è un esito 200 valido, non un errore — non trattarlo mai come un fallimento di trasporto. Gli errori veri usano codici di stato 4xx/5xx con un codice leggibile da macchina e un request_id per il supporto.

HTTP Codice errore Quando si verifica
400 invalid_iban L'IBAN ha fallito la validazione di formato o checksum.
400 missing_field Manca un campo obbligatorio (name o iban).
401 unauthorized Bearer token mancante o non valido.
429 rate_limited Troppe richieste — applica backoff e riprova.
503 scheme_unavailable Lo schema VoP / il PSP rispondente è temporaneamente irraggiungibile.
400 Bad Request 
{
  "error": "invalid_iban",
  "message": "The 'iban' field failed checksum validation.",
  "request_id": "req_8a2b1f0c"
}

Integra in quattro passaggi

Un'integrazione REST standard che si inserisce nel tuo flusso di pagamento esistente.

  1. 1

    Ottieni le credenziali

    Attivati e ricevi bearer token e base URL per sandbox e produzione.

  2. 2

    Chiama /verify

    Invia in POST nome e IBAN del beneficiario, con external_id e organisation_id opzionali.

  3. 3

    Leggi scheme_code

    Ramifica su MTCH / CMTC / NMTC / NOAP e salva il verification_id.

  4. 4

    Agisci nella tua UI

    Mostra un segnale chiaro a chi paga, o subordina all'esito una distinta o un mandato.

Riferimento API

FAQ per sviluppatori

Le prime domande dei team di integrazione.

Un body JSON con name e iban (obbligatori), più account_type, organisation_id (Partita IVA / Codice Fiscale per le persone giuridiche) ed external_id opzionali. Vedi l'esempio di richiesta qui sopra.

NO_MATCH (codice di schema NMTC) è una risposta 200 valida, non un errore. Trattala come uno stop deciso: avvisa chi paga, blocca l'approvazione automatica e richiedi un ricontrollo prima dell'invio.

Sì. I token sono rilasciati per ambiente, così puoi integrare e testare in sandbox prima di passare la base URL alla produzione.

Sì — invia organisation_id con account_type LEGAL_PERSON. Utile quando il nome commerciale differisce dalla ragione sociale registrata.

Invia il tuo external_id nella richiesta: viene restituito invariato e ogni risposta riporta anche un verification_id univoco.

Continua a leggere

L'API Verification of Payee Panoramica, destinatari e casi d'uso. RoxPay Verification of Payee Come il servizio è erogato su RoxPay. Glossario Termini VoP, SEPA e codici di schema.

Ottieni le credenziali API

Attivati sullo schema SEPA VoP con un'unica integrazione REST e vai live prima della scadenza.

Parla con un esperto Sull'API VoP