Documentation API Verification of Payee

Authentification

Chaque requête est authentifiée par un bearer token via HTTPS. Envoyez le token dans l'en-tête Authorization ; les tokens sont émis par environnement (sandbox et production).

Les mêmes identifiants débloquent aussi le tableau de bord RoxBusiness, où vous pouvez lancer des vérifications ponctuelles sans écrire de code.

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

Requête

Envoyez en POST un corps JSON avec le nom du bénéficiaire et l'IBAN. Pour les personnes morales, vous pouvez aussi envoyer un identifiant d'organisation (p. ex. une Partita IVA / Codice Fiscale italienne) et un external_id optionnel pour le rapprochement.

Corps de la requête

{
  "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"
  }'

Réponse

Une réponse 200 renvoie le résultat normalisé, le code de correspondance du schéma SEPA, le BIC de la banque répondante et le temps de traitement. En cas de correspondance proche, le nom vérifié est renvoyé dans suggested_name.

Corps de la réponse

{
  "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"
}

Codes de résultat de correspondance

Chaque réponse correspond à l'un des quatre codes du schéma SEPA VoP. Branchez-vous sur scheme_code pour que votre logique reste stable.

Gestion des erreurs

NO_MATCH est un résultat 200 valide, pas une erreur — ne le traitez jamais comme un échec de transport. Les vraies erreurs utilisent des codes de statut 4xx/5xx avec un code d'erreur lisible par machine et un request_id pour le support.

{
  "error": "invalid_iban",
  "message": "The 'iban' field failed checksum validation.",
  "request_id": "req_8a2b1f0c"
}

Intégrez en quatre étapes

Une intégration REST standard qui s'insère dans votre flux de paiement existant.

1. 1

   Obtenez les identifiants

   Faites l'onboarding et recevez votre bearer token et votre URL de base pour sandbox et production.

2. 2

   Appelez /verify

   Envoyez en POST le nom du bénéficiaire et l'IBAN, avec un external_id et un organisation_id optionnels.

3. 3

   Lisez scheme_code

   Branchez-vous sur MTCH / CMTC / NMTC / NOAP et stockez le verification_id.

4. 4

   Agissez dans votre UI

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