L'API Verification of Payee

Sì. Una chiamata di verifica risponde in modo sincrono, di norma in molto meno di un secondo, e include il BIC della banca rispondente e il tempo di elaborazione del PSP per monitorare le prestazioni.

Le chiamate sono autenticate con un bearer token su HTTPS. Puoi anche usare la dashboard RoxBusiness per verifiche estemporanee senza scrivere codice.

Un esito normalizzato (MATCH, CLOSE_MATCH, NO_MATCH, NOT_APPLICABLE), il codice di corrispondenza dello schema SEPA, un id di verifica, il BIC rispondente, il tempo di elaborazione e il tuo id esterno opzionale.

Sì - chiama l'endpoint per ogni record per verificare un intero file di fornitori o beneficiari prima di una distinta. È pensata per alti volumi.

Sì. L'endpoint è stateless, quindi puoi chiamarlo ogni volta che viene creato un beneficiario - ad esempio un passaggio di onboarding di un venditore o di un fornitore - e di nuovo subito prima di ogni pagamento. Il ricontrollo al momento del pagamento intercetta le coordinate bancarie cambiate dopo l'onboarding, dove di solito avviene la frode da dirottamento delle fatture e dei pagamenti.

La verifica è una chiamata REST per record, quindi un file di pagamento con migliaia di beneficiari si gestisce come un lotto: scorri il file, chiama l'endpoint per ogni record e raccogli gli esiti prima di rilasciare la distinta. Poiché l'API è pensata per volumi elevati, puoi scandire il ciclo in base alla tua finestra di rilascio, senza i limiti dell'onboarding banca per banca. Parlaci dei tuoi volumi e dimensioneremo il throughput insieme a te.

Sì. La stessa verifica è disponibile nella dashboard RoxBusiness, così un team finance o operations può controllare un singolo beneficiario - un controllo "know your payee" prima di inviare denaro - mentre gli sviluppatori usano l'API per i flussi automatizzati.

Sì. La verifica confronta il nome inviato con il titolare del conto registrato, sia esso una persona fisica o un'azienda, ed è usata nel flusso dei mandati SEPA Direct Debit di RoxPay come pre-controllo.

NO_MATCH non è un errore di trasporto: è una risposta 200 valida che indica che il nome non appartiene all'IBAN. Trattala come uno stop deciso nella tua UI o nella distinta: mostra un avviso chiaro, blocca l'approvazione automatica e fai ricontrollare il beneficiario prima dell'invio.

CLOSE_MATCH (codice di schema CMTC) significa che il nome è quasi esatto - manca un secondo nome, c'è una ragione sociale diversa dal nome commerciale. La risposta riporta il nome verificato del titolare, così puoi mostrarlo come suggerimento e chiedere conferma a chi paga invece di rifiutare il pagamento.

Per le persone giuridiche lo schema consente la verifica sull'identificativo dell'organizzazione (es. Partita IVA / Codice Fiscale) oltre che sul nome. Invii l'identificativo nella richiesta e l'API restituisce l'esito standard - utile quando ragione sociale e nome commerciale non coincidono.

Sì. Per una distinta, scorri il file di fornitori o stipendi e chiama l'endpoint di verifica per ogni record prima di rilasciare il lotto. È pensata per alti volumi, così la tesoreria può validare in blocco gli IBAN delle fatture fornitori prima di ogni bonifico.

Sì. Invii una richiesta JSON con nome del beneficiario e IBAN e ricevi l'esito, il nome verificato (in caso di corrispondenza parziale) e il BIC rispondente. Vedi una richiesta e una risposta complete nel nostro esempio VoP, o i payload e i codici di schema nella documentazione API.

Considera la chiamata di verifica come un passaggio in più prima dell'autorizzazione del pagamento. Autenticati con un bearer token, invia in POST nome e IBAN del beneficiario, leggi l'esito e poi ramifica: procedi su MATCH, mostra il nome suggerito e chiedi conferma su CLOSE_MATCH, blocca l'approvazione automatica su NO_MATCH e lascia decidere a chi paga su NOT_APPLICABLE. Poiché l'endpoint è stateless, la stessa chiamata si inserisce nel checkout, nell'onboarding dei fornitori, in una distinta o in un lotto di pagamenti senza modificare i tuoi canali di pagamento.

È entrambe le cose, a seconda dell'uso. Come controllo del beneficiario risponde alla domanda "a chi appartiene questo IBAN?" per un singolo beneficiario - utile per un team finance o per chi paga prima di inviare il denaro. Come API di validazione dei pagamenti esegue lo stesso controllo all'interno di un flusso automatizzato, così ogni pagamento o disposizione viene validato rispetto al titolare del conto prima di partire.

"Know your payee" è l'abitudine pratica di confermare il nome del titolare del conto prima di pagare, invece di fidarsi dei dati riportati su una fattura o in un'email. L'API trasforma questa abitudine in un passaggio automatizzato: il nome viene confrontato con l'IBAN e ottieni una risposta chiara - corrispondenza, corrispondenza parziale, nessuna corrispondenza o non possibile - in molto meno di un secondo.

Confirmation of Payee (CoP) è lo schema britannico di verifica del nome; Verification of Payee (VoP) è lo schema EPC usato in tutta l'UE e nello spazio SEPA. Se ti servono entrambi, cerca un provider che copra lo schema SEPA VoP con un'unica integrazione e restituisca gli esiti standardizzati, così il tuo codice non cambia da un mercato all'altro. RoxPay eroga la VoP come un'unica API REST, con i codici di schema, il BIC rispondente e il tempo di elaborazione in ogni risposta.

Cinque cose. Copertura: quali banche e quali Paesi il provider riesce a raggiungere in tutta la SEPA. Latenza: se gli esiti rientrano in modo affidabile nella finestra dei pagamenti istantanei. Accuratezza: come il confronto dei nomi gestisce le corrispondenze parziali e i nomi commerciali rispetto alle ragioni sociali. Direzioni: se la VoP in richiesta e in risposta passano dalla stessa integrazione. E assistenza: chi monitora il servizio e cosa succede quando un PSP rispondente non è raggiungibile. Fatti mettere per iscritto il payload della risposta e i codici di errore: dicono più di un elenco di funzionalità.

Ramifica sul codice dello schema, non sull'etichetta mostrata. Nella tua UI tratta MTCH come un via libera silenzioso, CMTC come un avviso leggero che mostra il nome suggerito e chiede conferma a chi paga, e NMTC come un avviso severo che blocca l'approvazione automatica. NOAP non è né l'uno né l'altro: significa che la verifica non è stata completata, quindi avvisa chi paga che la verifica non era disponibile e lascia decidere lui. Tenere separati i quattro codici nel tuo codice è ciò che rende prevedibile il comportamento degli avvisi.

Sì, e conviene farlo. L'endpoint è stateless, quindi la stessa chiamata verifica un beneficiario quando il record viene creato - un passaggio di onboarding di un venditore, di un fornitore o di un dipendente - e di nuovo subito prima che il denaro si muova. Il ricontrollo al momento del pagamento è ciò che intercetta le coordinate bancarie cambiate dopo l'onboarding, dove di solito avviene la frode da dirottamento dei pagamenti. Un solo endpoint serve entrambi i momenti, quindi non ne mantieni due.

Sì. Le credenziali della sandbox sono emesse separatamente da quelle di produzione, così puoi provare i flussi di corrispondenza, corrispondenza parziale e nessuna corrispondenza sull'API prima di andare live. Le stesse credenziali danno anche accesso alla dashboard RoxBusiness, dove puoi eseguire verifiche estemporanee senza scrivere codice.

Ricevi NOT_APPLICABLE (codice di schema NOAP) come risposta 200 valida, non come errore di trasporto. Significa che la verifica non è stata completata per quell'IBAN in quel momento. Trattalo come un dato sconosciuto e non come un guasto: informa chi paga che la verifica non era disponibile e lascia che decida se proseguire. I veri guasti tecnici usano i codici di stato 4xx e 5xx con un codice di errore leggibile dalla macchina.