Guía de integración con PHP

Validar un IBAN en un formulario PHP

Cree un pequeño formulario del lado del servidor que verifique un IBAN con IBAN-Test, mantenga su token API alejado del navegador e informe claramente a los clientes cuando no se puede completar una verificación.

Estado de las pruebas: Las pruebas incluidas utilizan una transmisión simulada y credenciales ficticias para comprobar resultados válidos, inválidos y no disponibles, rechazo de CSRF, escape de HTML y tiempos de espera. Simulan una transferencia fallida para probar el manejo de tiempos de espera sin esperar a la red. No constituyen una prueba autenticada de la API real. Ejecútelas al adaptar el ejemplo y verifique su entorno de pruebas antes de aceptar envíos de clientes reales.

1. Comprenda el flujo de solicitudes

El navegador muestra un formulario HTML normal. Cuando se envía, el IBAN y un token CSRF se transfieren de la sesión a su aplicación PHP. PHP verifica el token del formulario, delimita la entrada y elimina los espacios en blanco normales antes de solicitar la API. El navegador nunca se conecta directamente a IBAN-Test y no recibe el token al portador.

El backend envía JSON a POST https://www.iban-test.eu/api/v2/iban/validate. Lee el estado HTTP y los campos JSON, asigna el resultado a un mensaje de usuario específico y devuelve otra página HTML. La interfaz se describe en documentación de la API de IBAN-Test.

Browser form → your PHP backend → IBAN-Test API
Browser result ← controlled message ← HTTP status and JSON

Mantenga esta división incluso con una personalización de AJAX: JavaScript puede llamar a su propia aplicación, pero la autenticación en IBAN-Test permanece en el servidor. Un token en un archivo JavaScript o paquete minimizado no es secreto.

2. Inicie el ejemplo localmente

Descomprima el archivo ZIP y vaya al directorio demo. Verifique la versión de PHP y la extensión cURL usando php -v y php -m. Las sesiones y JSON también deben estar disponibles. No se requiere compositor. Primero, ejecute las comprobaciones fuera de línea incluidas:

php tests/run.php

Para realizar pruebas API reales, necesitará un token de su cuenta IBAN-Test. En Bash, use entradas ocultas para que el valor no termine en el historial del shell como un comando de texto sin formato:

read -r -s -p 'IBAN-Test API token: ' IBAN_TEST_API_TOKEN
printf '\n'
export IBAN_TEST_API_TOKEN
php -d display_errors=0 -d post_max_size=4K -S 127.0.0.1:8080 -t public

Abra http://127.0.0.1:8080. El servidor solo escucha en su computadora. Deténgalo con Ctrl+C y luego ejecute unset IBAN_TEST_API_TOKEN. Para este ejercicio local se utiliza el servidor de desarrollo PHP. Deje public configurado como raíz del documento para mantener el cliente, las pruebas y el archivo README fuera del directorio enviado.

Sin la variable de entorno, el formulario aún se cargará. Si la entrada es plausible, muestra un mensaje de indisponibilidad sin consultar la API. Las solicitudes de API reales requieren una cuenta activa y consumen cuota.

3. Verifique previamente las entradas y proteja el formulario.

El ejemplo acepta una cadena de hasta 80 bytes, elimina los espacios ordinarios, normaliza las letras a mayúsculas y comprueba un patrón básico de caracteres. Así rechaza entradas claramente inadecuadas con poco coste. Estas comprobaciones no calculan la suma de control ni confirman la validez del IBAN; el servidor sigue necesitando el resultado de la API.

Un token aleatorio almacenado en la sesión se envía como un campo oculto y se compara cuando se envía. Se rechaza un token diferente antes de la llamada a la API. También hay un período de espera de tres segundos entre entradas por sesión. Esto ayuda contra los clics repetidos, pero no es un límite de tasa productiva ya que los usuarios pueden crear nuevas sesiones.

Todos los valores insertados en HTML están enmascarados con htmlspecialchars, incluida la entrada que se vuelve a mostrar después de un error. La implementación escapa explícitamente de las comillas y reemplaza secuencias UTF-8 no válidas según Referencia de enmascaramiento PHP. Las respuestas del navegador utilizan Cache-Control: no-store. Las cookies de sesión utilizan HttpOnly y SameSite; Las opciones se explican en el Documentación de sesión PHP.

4. Envíe una solicitud de API limitada

El cliente lee IBAN_TEST_API_TOKEN en el servidor y envía un encabezado Authorization: Bearer. El contenido de la solicitud solo contiene el IBAN normalizado:

{"iban":"DE89370400440532013000"}

El objetivo está especificado en el código. Los envíos de formularios no pueden seleccionar un anfitrión. El certificado TLS y el nombre de host aún están verificados; Los redireccionamientos están deshabilitados. El establecimiento de la conexión está limitado a tres segundos y la transmisión completa está limitada a ocho segundos. Una respuesta superior a 64 KiB aborta la transmisión. Las opciones se describen en el referencia de cURL de PHP.

No hay repetición automática. Después de un tiempo de espera, es posible que no quede claro si el proveedor procesó la solicitud; Las repeticiones pueden consumir cuota adicional. Por eso la página muestra un error temporal. Si su aplicación luego agrega reintentos, defina una estrategia limitada que tenga en cuenta tanto la latencia como la cuota.

5. Muestra el resultado correcto.

Verifique tanto la transmisión exitosa como los campos de respuesta. Para este punto final, el ejemplo según códigos de resultados documentados cubre tres casos:

• Válido: HTTP 200, el valor entero code: 2100 y el valor booleano error: false deben estar presentes juntos.
• Datos bancarios no válidos: Una respuesta HTTP 200 construida correctamente con el código 3100, 3101 o 3102 y el valor booleano error: true solicita corrección. Las respuestas contradictorias con error: false se consideran no disponibles.
• No disponible: Los problemas de autenticación o cuota, diferentes valores de estado HTTP, tiempos de espera, códigos desconocidos y JSON incorrecto producen un mensaje de error técnico.

Si la comprobación no está disponible, no debe indicar al cliente que su IBAN es inválido. El ejemplo utiliza mensajes propios en lugar del texto sin filtrar del proveedor. Un resultado válido confirma la validación formal, no la titularidad, la existencia de la cuenta ni el éxito de un pago.

6. Prepare la aplicación para la operación.

Antes de publicar el formulario, exija autorización en su aplicación y aplique un presupuesto de cuota compartido entre usuarios, sesiones e instancias. En compras como invitado, vincule el acceso a una sesión de compra autorizada por el servidor y añada medidas contra abusos. La espera entre envíos y la comprobación CSRF no protegen por sí solas su cuota de pago.

Utilice HTTPS, cookies seguras, un servidor PHP de nivel de producción y límites de tamaño de contenido de solicitud del lado del servidor. Configure explícitamente servidores proxy confiables cuando TLS finalice en sentido ascendente. Proporcionar secretos sobre su entorno de alojamiento; PHP-FPM puede requerir una configuración de entorno explícita. Excluya tokens, contenido de solicitudes de IBAN y detalles confidenciales de errores de los registros y el monitoreo. Nunca publique una página de diagnóstico que genere las variables de entorno.