Referencia API

Documentación API Verification of Payee

Autenticación, el endpoint de verificación, payloads de solicitud y respuesta, códigos de coincidencia del esquema SEPA y gestión de errores — todo lo que un desarrollador necesita para integrar el control IBAN/nombre, con ejemplos JSON y cURL listos para copiar.

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

La URL base y las credenciales API se proporcionan en el onboarding — contáctenos para obtenerlas.

La API Verification of Payee es un único endpoint REST autenticado: envía por POST un nombre de beneficiario y un IBAN y recibe un resultado de coincidencia estandarizado en tiempo real. Los ejemplos siguientes son ilustrativos; su URL base y sus credenciales exactas se emiten durante el onboarding.

Autenticación

Cada solicitud se autentica con un bearer token sobre HTTPS. Envíe el token en la cabecera Authorization; los tokens se emiten por entorno (sandbox y producción).

Las mismas credenciales también desbloquean el panel RoxBusiness, donde puede ejecutar verificaciones puntuales sin escribir código.

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

Solicitud

Envíe por POST un cuerpo JSON con el nombre del beneficiario y el IBAN. Para personas jurídicas también puede enviar un identificador de organización (p. ej. una Partita IVA / Codice Fiscale italianos) y un external_id opcional para la conciliación.

Cuerpo de la solicitud

Campo Tipo Requerido Descripción
name string Requerido Nombre del beneficiario a verificar, tal como lo introdujo el pagador.
iban string Requerido IBAN de destino (validado para formato y checksum antes de la llamada al esquema).
account_type enum Opcional NATURAL_PERSON o LEGAL_PERSON. Ayuda al banco respondedor a comparar correctamente.
organisation_id string Opcional Número de IVA / código fiscal para personas jurídicas (p. ej. Partita IVA). Verificado frente al titular registrado.
external_id string Opcional Su propio id de referencia, devuelto en la respuesta para la conciliación.
Cuerpo de la solicitud 
{
  "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"
  }'

Respuesta

Una respuesta 200 devuelve el resultado normalizado, el código de coincidencia del esquema SEPA, el BIC del banco respondedor y el tiempo de procesamiento. En una coincidencia parcial, el nombre verificado se devuelve en suggested_name.

Cuerpo de la respuesta

Campo Tipo Descripción
verification_id string Id único de esta verificación, para su pista de auditoría.
result enum MATCH, CLOSE_MATCH, NO_MATCH o NOT_APPLICABLE.
scheme_code string El código del esquema SEPA VoP: MTCH, CMTC, NMTC o NOAP.
suggested_name string En CLOSE_MATCH, el nombre verificado del titular a sugerir al pagador.
responding_bic string BIC de la entidad que respondió a la verificación.
processing_time_ms integer Tiempo que tardó el PSP respondedor, en milisegundos.
external_id string Su id de referencia, devuelto sin cambios.
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"
}

Códigos de resultado de coincidencia

Cada respuesta corresponde a uno de los cuatro códigos del esquema SEPA VoP. Ramifique sobre scheme_code para que su lógica se mantenga estable.

Código Resultado Significado Acción recomendada
MTCH MATCH El nombre coincide con el titular de la cuenta. Proceda con confianza.
CMTC CLOSE_MATCH Casi correcto (p. ej. nombre comercial vs razón social). Muestre suggested_name; pida al pagador que confirme.
NMTC NO_MATCH El nombre no pertenece al IBAN. Parada firme — avise y bloquee la aprobación automática.
NOAP NOT_APPLICABLE La verificación no pudo completarse. Informe al pagador; deje que decida.

Gestión de errores

NO_MATCH es un resultado 200 válido, no un error — nunca lo trate como un fallo de transporte. Los errores reales usan códigos de estado 4xx/5xx con un código de error legible por máquina y un request_id para soporte.

HTTP Código de error Cuándo ocurre
400 invalid_iban El IBAN falló la validación de formato o checksum.
400 missing_field Falta un campo requerido (name o iban).
401 unauthorized Bearer token ausente o inválido.
429 rate_limited Demasiadas solicitudes — aplique backoff y reintente.
503 scheme_unavailable El esquema VoP / el PSP respondedor está temporalmente inaccesible.
400 Bad Request 
{
  "error": "invalid_iban",
  "message": "The 'iban' field failed checksum validation.",
  "request_id": "req_8a2b1f0c"
}

Integre en cuatro pasos

Una integración REST estándar que encaja en su flujo de pago existente.

  1. 1

    Obtenga credenciales

    Haga el onboarding y reciba su bearer token y URL base para sandbox y producción.

  2. 2

    Llame a /verify

    Envíe por POST el nombre del beneficiario y el IBAN, con un external_id y organisation_id opcionales.

  3. 3

    Lea scheme_code

    Ramifique sobre MTCH / CMTC / NMTC / NOAP y guarde el verification_id.

  4. 4

    Actúe en su UI

    Muestre una señal clara al pagador, o condicione una remesa o un mandato al resultado.

Referencia API

FAQ para desarrolladores

Las primeras preguntas de los equipos de integración.

Un cuerpo JSON con name e iban (requeridos), más account_type, organisation_id (IVA/código fiscal para personas jurídicas) y su external_id opcionales. Vea el ejemplo de solicitud anterior.

NO_MATCH (código de esquema NMTC) es una respuesta 200 válida, no un error. Trátela como una parada firme: avise al pagador, bloquee la aprobación automática y exija una nueva comprobación antes de enviar.

Sí. Los tokens se emiten por entorno, así que puede integrar y probar en sandbox antes de cambiar la URL base a producción.

Sí — envíe organisation_id con account_type LEGAL_PERSON. Ayuda cuando el nombre comercial difiere del nombre registrado.

Envíe su propio external_id en la solicitud; se devuelve sin cambios, y cada respuesta lleva también un verification_id único.

Sigue leyendo

La API Verification of Payee Visión general, públicos y casos de uso. RoxPay Verification of Payee Cómo se ofrece el servicio en RoxPay. Glosario Términos VoP, SEPA y códigos de esquema.

Obtenga sus credenciales API

Haga el onboarding al esquema SEPA VoP con una integración REST y entre en producción antes de su plazo.

Hablar con un experto Sobre la API VoP