Pour les développeurs

L'API Verification of Payee

Un appel REST en temps réel pour confirmer le nom d'un bénéficiaire par rapport à un IBAN - résultat, BIC de la banque répondante et temps de traitement dans la réponse. Conçue sur la plateforme RoxPay et le schéma SEPA VoP.

POST /v4/iban-check/verify/vop
Request
{
  "Name": "ACME Trading Ltd",
  "Iban": "DE89 3704 0044 0532 0130 00"
}
verifying…
Response 200 OK 412 ms
{
  "VopResult": "MATCH",
  "MatchType": "MTCH",
  "RespondingBic": "CRACIT33XXX"
}
Aperçu

Qu'est-ce qu'une API Verification of Payee ?

Une API Verification of Payee est un service web qui répond à une seule question : ce nom appartient-il à cet IBAN ? Vous envoyez le nom du bénéficiaire et l'IBAN, et vous recevez en retour un résultat de correspondance standardisé, en temps réel. C'est le même contrôle que celui affiché au payeur à l'écran, exposé sous forme d'appel que votre logiciel peut effectuer - le schéma SEPA VoP derrière un seul endpoint REST authentifié, sans messagerie de schéma à construire vous-même.

Vous l'appelez au moment où un bénéficiaire est créé ou juste avant qu'un paiement ne parte : un checkout, une fiche fournisseur, un ordre de paiement. La réponse arrive de façon synchrone, ce qui vous permet de montrer le nom vérifié au payeur - ou de bloquer le paiement - avant son envoi. C'est la même vérification que RoxPay exécute dans sa plateforme bancaire SwiftLine / RoxBusiness, disponible pour les banques, les PSP et les entreprises via l'API et un tableau de bord.

Si vous cherchez une API Confirmation of Payee, c'est le même contrôle sous son nom européen : Confirmation of Payee (CoP) est le schéma britannique, Verification of Payee (VoP) est le schéma EPC utilisé dans toute l'UE et l'espace SEPA. Vous envoyez en POST un nom et un IBAN, et vous recevez le résultat de correspondance, le code du schéma, le BIC de la banque répondante et le temps de traitement - aucune session, aucune URL de callback, aucune intégration banque par banque.

Intégration

Comment intégrer l'API Verification of Payee dans votre flux de paiement

Une intégration REST standard qui s'insère dans votre flux de paiement existant - des identifiants à un contrôle en production en cinq étapes.

1

Obtenez vos identifiants

Activez le service et authentifiez-vous avec un bearer token - aucun onboarding banque par banque à gérer.

2

Envoyez nom + IBAN

Envoyez en POST le nom et l'IBAN du bénéficiaire à l'endpoint de vérification, avec un id de référence optionnel pour le rapprochement.

3

Lisez le résultat

Recevez le résultat (correspondance / correspondance proche / aucune correspondance / non applicable), le BIC répondant et le temps de traitement.

4

Branchez selon le résultat

Poursuivez sur MATCH, affichez le nom suggéré et demandez confirmation sur CLOSE_MATCH, bloquez l'approbation automatique sur NO_MATCH, laissez le payeur décider sur NOT_APPLICABLE.

5

Agissez dans votre UI

Affichez un signal clair au payeur, ou conditionnez au résultat une remise, un mandat ou une étape d'onboarding.

Dans votre flux

Où se situe l'appel dans un flux de paiement réel

L'endpoint est sans état, donc le même appel convient à chaque étape où les coordonnées d'un bénéficiaire sont saisies ou réutilisées - y compris pour vérifier les bénéficiaires à l'onboarding puis de nouveau au moment du paiement.

Onboarding du bénéficiaire

Vérifiez l'IBAN d'un vendeur, d'un fournisseur ou d'un salarié dès son ajout, et stockez le nom vérifié à côté de la fiche.

Checkout et paiements ponctuels

Appelez l'API pendant que le payeur est encore à l'écran, pour qu'une non-correspondance soit détectée avant l'autorisation.

Remises et paiements en masse

Parcourez le fichier et vérifiez chaque bénéficiaire avant de libérer le lot, puis ne retenez que les exceptions.

Re-contrôle avant paiement

Vérifiez à nouveau juste avant que l'argent ne parte - c'est dans les coordonnées bancaires modifiées après l'onboarding que se cache la fraude au détournement.

Vérification de compte en temps réel

Comment utiliser l'API pour la vérification de compte en temps réel

Un contrat requête/réponse synchrone, pour que la réponse soit disponible pendant que le payeur décide encore.

Synchrone par conception

L'appel de vérification répond dans la même requête - généralement bien en dessous d'une seconde - sans polling, webhook ni file d'attente.

Les temps dans la réponse

Chaque réponse contient le temps de traitement du PSP, ce qui vous permet de suivre la latence et d'alerter comme pour n'importe quelle autre API.

Conçue pour les paiements instantanés

Le contrôle tient dans la fenêtre des paiements instantanés SEPA : la vérification ne devient jamais la raison d'un paiement en retard.

Nouveaux essais idempotents

Transmettez un id externe stable à chaque appel pour qu'un nouvel essai ne crée pas de vérification en double et que chaque résultat reste traçable.

Un appel, une réponse

La vérification de compte en temps réel se résume à un POST nom + IBAN dont vous lisez le résultat : aucune session, aucune URL de callback et aucun état à conserver entre les appels.

Masse et volume

Vérifications de bénéficiaires en masse sans buter sur les limites de débit

Pour les fichiers de paiement comptant des milliers de bénéficiaires, la vérification est un appel par enregistrement que vous cadencez vous-même - un gros fichier est donc une question de débit, pas un obstacle. Dimensionnez la boucle sur votre fenêtre de remise et parlez-nous de vos volumes.

Un appel par enregistrement

Parcourez votre fichier de bénéficiaires et appelez l'endpoint de vérification pour chaque bénéficiaire - le contrat est identique que vous envoyiez un enregistrement ou dix mille.

Un débit dimensionné avec vous

L'API est conçue pour un débit élevé et vous cadencez la boucle selon votre propre fenêtre de remise, sans être plafonné par un onboarding banque par banque.

Collecter, puis libérer

Rassemblez les résultats de tout le fichier, libérez automatiquement les correspondances et orientez les correspondances proches et les non-correspondances vers une file de revue humaine.

Réutiliser le nom vérifié

Stockez le nom vérifié du titulaire sur la fiche du bénéficiaire pour que les remises suivantes puissent le comparer et signaler les changements silencieux.

Cas d'usage

Marketplaces, paie et comptes fournisseurs

Le même endpoint couvre l'onboarding et le moment du paiement - les deux instants où les coordonnées du bénéficiaire sont les plus exposées. Pour une marketplace, cela signifie vérifier un vendeur à son onboarding puis de nouveau avant chaque paiement, depuis une seule intégration.

Marketplaces et plateformes

Vérifiez l'IBAN d'un vendeur à son onboarding, puis vérifiez à nouveau avant chaque paiement. Le re-contrôle au moment du paiement détecte les coordonnées bancaires modifiées après l'onboarding, là où se produit généralement la fraude au détournement de paiement. Le même endpoint sert ces deux moments : vous n'avez pas besoin d'un contrôle d'onboarding et d'un contrôle de paiement distincts.

Paie

Vérifiez les IBAN des salariés à leur ajout et de nouveau avant le jour de paie, pour qu'un salaire ne parte jamais vers un compte qui n'appartient plus au salarié.

Comptes fournisseurs

Validez en masse les IBAN des fournisseurs par rapport aux noms avant de libérer une remise, et ne retenez que les enregistrements qui reviennent en correspondance proche ou en non-correspondance.

Trésorerie et ERP

Appelez l'API depuis votre ERP ou votre système de trésorerie pour que la vérification fasse partie de la préparation du fichier de paiement, et non d'une étape manuelle séparée.

Réponse

Ce que l'API renvoie : correspondance, correspondance proche, aucune correspondance

Chaque réponse correspond à un code du schéma SEPA VoP, votre logique reste donc simple. Branchez sur le code, pas sur la formulation. Un résultat de correspondance est une réponse 200 valide - seules les défaillances techniques reviennent en 4xx ou 5xx.

MATCH · MTCH

Le nom correspond au titulaire du compte. La réponse contient aussi le BIC de la banque répondante. Poursuivez en confiance.

CLOSE_MATCH · CMTC

Correspondance proche - presque exacte, par exemple un nom commercial face à une raison sociale. Affichez le nom vérifié comme suggestion et demandez confirmation au payeur.

NO_MATCH · NMTC

Aucune correspondance : le nom n'appartient pas à cet IBAN. Affichez un avertissement clair avant la confirmation du paiement et bloquez l'approbation automatique.

NOT_APPLICABLE · NOAP

Non applicable : la vérification n'est pas disponible pour cet IBAN pour le moment. Informez le payeur et laissez-le décider.

Construire vs. intégrer

Construire la VoP soi-même vs. l'API

Ce que vous évitez en appelant un endpoint plutôt qu'en rejoignant le schéma seul.

Développement interne

  • Connectivité au schéma Intégration par PSP répondant
  • Délai de mise en production Mois
  • Détail de la réponse Vous la normalisez
  • Contrôles de bénéficiaires en masse Vous construisez et cadencez la boucle
  • Les deux sens de la VoP Demande et réponse construites séparément
  • Réutilisation entre produits À recâbler pour chaque flux
  • Maintenance À votre charge

API Verification of Payee

  • Connectivité au schéma Une connexion, portée SEPA
  • Délai de mise en production Semaines
  • Détail de la réponse Résultat standardisé + BIC + temps
  • Contrôles de bénéficiaires en masse Des appels par enregistrement dimensionnés sur votre fenêtre de remise
  • Les deux sens de la VoP Demande et réponse via une seule intégration
  • Réutilisation entre produits Une API pour UI, lot et mandats
  • Maintenance Gérée par la plateforme
À qui elle s'adresse

Une API, trois publics

Le même endpoint répond à des besoins très différents - pour les payeurs particuliers comme pour les payeurs professionnels, puisque le contrôle compare le nom soumis au titulaire enregistré du compte, qu'il s'agisse d'une personne physique ou d'une entreprise.

Banques et PSP

Offrez la Verification of Payee aux titulaires de comptes et respectez le Règlement sur les paiements instantanés sans construire la connectivité au schéma.

Développeurs

Un contrat REST prévisible, des réponses en temps réel, vos propres id de référence et des codes de schéma clairs sur lesquels brancher.

Entreprises et ERP

Vérifiez en masse les IBAN des fournisseurs et de la paie avant une remise, réduisant le risque de détournement de factures.

FAQ

L'API, en réponses

Les premières questions des développeurs et équipes produit.

Oui. Un appel de vérification répond de manière synchrone, généralement en bien moins d'une seconde, et inclut le BIC de la banque répondante et le temps de traitement du PSP pour surveiller les performances.

Les appels sont authentifiés avec un bearer token sur HTTPS. Vous pouvez aussi utiliser le tableau de bord RoxBusiness pour des contrôles ponctuels sans écrire de code.

Un résultat normalisé (MATCH, CLOSE_MATCH, NO_MATCH, NOT_APPLICABLE), le code de type de correspondance du schéma SEPA, un id de vérification, le BIC répondant, le temps de traitement et votre id externe optionnel.

Oui - appelez l'endpoint par enregistrement pour vérifier un fichier entier de fournisseurs ou bénéficiaires avant une remise. Elle est conçue pour de gros volumes.

Oui. L'endpoint est sans état, vous pouvez donc l'appeler à chaque création de bénéficiaire - une étape d'onboarding vendeur ou fournisseur - et de nouveau juste avant chaque paiement. Le re-contrôle au moment du paiement détecte les coordonnées bancaires modifiées après l'onboarding, là où se produit généralement la fraude au détournement de facture et de paiement.

La vérification est un appel REST par enregistrement : un fichier de paiement de milliers de bénéficiaires se traite donc comme un lot - parcourez le fichier, appelez l'endpoint par enregistrement et rassemblez les résultats avant de libérer la remise. Comme l'API est conçue pour un débit élevé, vous cadencez la boucle selon votre propre fenêtre de remise, sans être plafonné par un onboarding banque par banque. Parlez-nous de vos volumes et nous dimensionnerons le débit avec vous.

Oui. La même vérification est disponible dans le tableau de bord RoxBusiness : une équipe finance ou opérations peut contrôler un bénéficiaire unique - un contrôle « know your payee » avant d'envoyer de l'argent - pendant que les développeurs utilisent l'API pour les flux automatisés.

Oui. Le contrôle compare le nom soumis au titulaire du compte enregistré, qu'il s'agisse d'une personne physique ou d'une entreprise, et est utilisé dans le flux des mandats SEPA Direct Debit de RoxPay comme pré-contrôle.

NO_MATCH n'est pas une erreur de transport - c'est une réponse 200 valide indiquant que le nom n'appartient pas à l'IBAN. Traitez-la comme un arrêt net dans votre UI ou votre remise : affichez un avertissement clair, bloquez l'approbation automatique et faites revérifier le bénéficiaire avant l'envoi.

CLOSE_MATCH (code de schéma CMTC) signifie que le nom est presque exact - un deuxième prénom manquant, une raison sociale vs un nom commercial. La réponse contient le nom vérifié du titulaire, vous pouvez donc l'afficher comme suggestion et demander confirmation au payeur plutôt que de rejeter le paiement.

Pour les personnes morales, le schéma permet la vérification par rapport à l'identifiant de l'organisation (par ex. la Partita IVA / le Codice Fiscale italien) ainsi qu'au nom. Vous soumettez l'identifiant dans la requête et l'API renvoie le résultat standard - utile lorsque la raison sociale et le nom commercial diffèrent.

Oui. Pour une remise, parcourez votre fichier de fournisseurs ou de paie et appelez l'endpoint de vérification par enregistrement avant de libérer le lot. Conçue pour de gros volumes, elle permet aux équipes financières de valider en masse les IBAN par rapport aux noms avant chaque remise.

Oui. Vous envoyez une requête JSON avec le nom et l'IBAN du bénéficiaire et recevez en retour le résultat, le nom vérifié (en cas de correspondance proche) et le BIC répondant. Retrouvez une requête et une réponse complètes dans notre exemple VoP, ou les payloads et codes de schéma dans la documentation API.

Traitez l'appel de vérification comme une étape supplémentaire avant l'autorisation du paiement. Authentifiez-vous avec un bearer token, envoyez en POST le nom et l'IBAN du bénéficiaire, lisez le résultat, puis branchez : poursuivez sur MATCH, affichez le nom suggéré et demandez confirmation sur CLOSE_MATCH, bloquez l'approbation automatique sur NO_MATCH et laissez le payeur décider sur NOT_APPLICABLE. L'endpoint étant sans état, le même appel s'insère dans un checkout, un onboarding fournisseur, une remise ou un lot de paiements sans modifier vos rails de paiement.

Des deux, selon l'usage. Comme contrôle de bénéficiaire, elle répond à la question « à qui appartient cet IBAN ? » pour un bénéficiaire unique - utile pour une équipe finance ou un payeur avant d'envoyer de l'argent. Comme API de validation des paiements, elle exécute le même contrôle dans un flux automatisé, de sorte que chaque paiement ou versement est validé par rapport au titulaire du compte avant de partir.

« Know your payee » désigne le réflexe pratique de confirmer le nom du titulaire du compte avant de payer, plutôt que de faire confiance aux coordonnées d'une facture ou d'un e-mail. L'API transforme ce réflexe en étape automatisée : le nom est comparé à l'IBAN et vous obtenez une réponse claire - correspondance, correspondance proche, aucune correspondance ou non applicable - en bien moins d'une seconde.

Confirmation of Payee (CoP) est le schéma britannique de contrôle de nom ; Verification of Payee (VoP) est le schéma EPC utilisé dans toute l'UE et l'espace SEPA. Si vous avez besoin des deux, cherchez un fournisseur qui couvre le schéma SEPA VoP via une seule intégration et renvoie les résultats standardisés, pour que votre code ne change pas d'un marché à l'autre. RoxPay fournit la VoP comme une seule API REST, avec les codes de schéma, le BIC répondant et le temps de traitement dans chaque réponse.

Cinq choses. La couverture : quelles banques et quels pays le fournisseur peut atteindre dans tout l'espace SEPA. La latence : si les résultats tiennent de façon fiable dans la fenêtre des paiements instantanés. La précision : comment le rapprochement des noms gère les correspondances proches et les noms commerciaux face aux raisons sociales. Les sens : si la VoP en demande et en réponse passe par la même intégration. Et le support : qui surveille le service et ce qui se passe quand un PSP répondant est injoignable. Demandez par écrit le payload de réponse et les codes d'erreur : ils vous en disent plus qu'une liste de fonctionnalités.

Branchez sur le code du schéma, pas sur le libellé affiché. Dans votre UI, traitez MTCH comme un passage silencieux, CMTC comme un avertissement souple qui affiche le nom suggéré et demande confirmation au payeur, et NMTC comme un avertissement ferme qui bloque l'approbation automatique. NOAP n'est ni l'un ni l'autre : cela signifie que le contrôle n'a pas pu être mené à bien, donc indiquez au payeur que la vérification était indisponible et laissez-le décider. C'est en gardant les quatre codes distincts dans votre code que le comportement des avertissements devient prévisible.

Oui, et c'est même recommandé. L'endpoint est sans état : le même appel vérifie un bénéficiaire à la création de la fiche - une étape d'onboarding vendeur, fournisseur ou salarié - puis de nouveau juste avant que l'argent ne parte. C'est le re-contrôle au moment du paiement qui détecte les coordonnées bancaires modifiées après l'onboarding, là où se produit généralement la fraude au détournement de paiement. Un seul endpoint sert ces deux moments : vous ne maintenez donc pas deux contrôles.

Vous recevez NOT_APPLICABLE (code de schéma NOAP) comme réponse 200 valide, et non comme erreur de transport. Cela signifie que le contrôle n'a pas pu être mené à bien pour cet IBAN à ce moment-là. Traitez-le comme une inconnue plutôt que comme une panne : informez le payeur que la vérification était indisponible et laissez-le décider s'il poursuit. Les vraies défaillances techniques utilisent les codes de statut 4xx et 5xx avec un code d'erreur lisible par une machine.

Le PSP demandeur est la banque du payeur : c'est lui qui envoie la demande de vérification. Le PSP répondant est la banque du bénéficiaire : c'est lui qui détient le compte et répond avec le résultat de correspondance. Le schéma EPC définit comment les deux échangent ce message ; avec l'API, vous vous contentez d'émettre la requête et de lire la réponse, sans construire vous-même la messagerie inter-PSP.

Non. L'EPC publie les spécifications de l'API inter-PSP Verification of Payee que les PSP utilisent pour échanger requêtes et réponses. Une API VoP encapsule cette messagerie : vous envoyez un nom et un IBAN en REST et recevez le résultat standardisé, le code du schéma et le BIC répondant, sans implémenter la messagerie du schéma ni vous intégrer à chaque banque répondante.

Cadencez la boucle sur votre fenêtre de remise plutôt que d'envoyer tout un fichier de paiement d'un coup. Si vous envoyez plus vite que le débit convenu, vous recevez un 429 : ralentissez et réessayez après un délai. Pour les défaillances 5xx, réessayez avec le même id externe pour que le nouvel essai ne crée pas de vérification en double. Pour les 4xx, corrigez la requête : un IBAN mal formé, un nom manquant ou des identifiants invalides ne réussiront pas lors d'un nouvel essai.

L'API répond à une seule question - ce nom appartient-il à cet IBAN - et renvoie le résultat du schéma. Ce résultat est un signal fort à injecter dans vos propres règles de fraude et de risque : une non-correspondance sur un bénéficiaire dont les coordonnées bancaires ont été modifiées récemment est exactement le schéma qui mérite d'être escaladé. Gardez le résultat de la vérification et votre décision de filtrage séparés dans vos journaux, pour voir lequel a bloqué un paiement.

Non, elles répondent à des questions différentes. La validation d'IBAN vérifie que l'IBAN est bien formé - format du pays et clé de contrôle - mais ne dit rien sur le propriétaire du compte. La Verification of Payee demande à la banque du bénéficiaire si le nom appartient à cet IBAN. Utilisez les deux : la validation intercepte les fautes de frappe avant l'appel, la vérification intercepte un IBAN valide qui appartient à quelqu'un d'autre.

Oui. Les identifiants du sandbox sont émis séparément de ceux de production, ce qui vous permet de dérouler des scénarios de correspondance, de correspondance proche et de non-correspondance sur l'API avant de passer en production. Testez aussi les cas défavorables - une réponse NOAP, un 429 et un 5xx - pour que votre logique de nouveaux essais et d'avertissements soit éprouvée avant que de l'argent réel ne circule. Les mêmes identifiants donnent aussi accès au tableau de bord RoxBusiness, où vous pouvez lancer des contrôles ponctuels sans écrire de code.

Poursuivez la lecture

Documentation API Payloads, codes de schéma et exemples de code. Comparatif d'API Développer en interne ou intégrer un fournisseur. Guide d'intégration Étape par étape, de l'accès au sandbox à un flux VoP en production. Guide d'intégration API (blog) L'authentification, la requête et les quatre résultats. Les codes de réponse expliqués MTCH, CMTC, NMTC et NOAP en pratique. La VoP pour les marketplaces Vérifiez les vendeurs à l'onboarding et au moment du paiement. La VoP pour la paie Contrôlez les IBAN des salariés avant le jour de paie. La VoP pour les comptes fournisseurs Validez en masse les IBAN des fournisseurs avant une remise. RoxPay Verification of Payee Comment le service est fourni sur la plateforme RoxPay. Comment RoxPay met en œuvre la Verification of Payee Le schéma SEPA, le trio IBAN et le pré-contrôle SDD. Comment fonctionne la VoP Le flux de bout en bout derrière l'API. Limites de débit et volume Comment dimensionner les contrôles de bénéficiaires en masse. La VoP pour le SaaS et les marketplaces Vérifiez les bénéficiaires à l'onboarding et au paiement. Contrôles IBAN en masse depuis votre ERP Validez en masse un fichier de paiement avant sa libération. Démo et sandbox Découvrez l'API, puis testez-la avec un accès au sandbox. Couverture bancaire Quelles institutions l'API peut atteindre dans tout l'espace SEPA. VoP vs validation d'IBAN Le contrôle de format et le contrôle de nom ne sont pas la même chose. Le rulebook du schéma EPC Les règles derrière les codes de correspondance. Supervision et observabilité Ce qu'il faut journaliser et surveiller en production. Exemple VoP Exemple concret Payee verification Les bases Précision VoP Appariement & précision VoP vs Confirmation of Payee Comparaison de concepts

Intégrez la Verification of Payee

Obtenez vos identifiants et passez en production sur le schéma SEPA VoP avec une seule intégration REST.