Cómo integrar Redsys y Bizum en Drupal Commerce sin perder la cabeza

La primera vez que conecté un Drupal Commerce con el TPV virtual del banco me pasé tarde y media peleándome con un error SIS0042 que no había forma de quitar. Spoiler: era la clave de cifrado, que tenía un espacio pegado al copiarla del PDF que me mandó el banco. Si vas a vender en España, tarde o temprano te toca Redsys, así que voy a contarte cómo montarlo bien a la primera y dónde están los charcos en los que yo ya me he metido.

Qué es Redsys y por qué casi no te lo puedes saltar en España

Redsys es la plataforma que está detrás del TPV virtual de la mayoría de bancos españoles. Cuando contratas una pasarela de pago con BBVA, Santander, CaixaBank, Sabadell, Unicaja o casi cualquier entidad nacional, lo que de verdad estás usando por debajo es Redsys. Cambia el logo y el panel de administración según el banco, pero el protocolo, los parámetros y la mecánica son los mismos.

Esto tiene una consecuencia práctica muy buena: aprendes a integrar Redsys una vez y te vale para casi cualquier cliente español, independientemente de con qué banco trabaje. Y tiene otra menos buena: el sistema arrastra años de documentación regular, mensajes de error crípticos y un panel de administración que parece de 2008. Forma parte del paquete.

Bizum, por su parte, no es una pasarela aparte que tengas que integrar por separado. En el contexto de comercio electrónico, Bizum se ofrece como un método de pago más a través de Redsys. Es decir, una vez tienes el TPV virtual funcionando y has activado Bizum en tu comercio, aparece como una opción de pago dentro del mismo flujo de Redsys. No hay un segundo SDK ni un segundo conjunto de claves: es la misma integración con una opción más activada.

Lo que necesitas antes de tocar Drupal

Aquí es donde mucha gente se atasca, porque la parte técnica de Drupal es la fácil. Lo costoso es el papeleo con el banco. Antes de instalar nada, asegúrate de tener:

1. El TPV virtual contratado con tu banco. Es un producto que se contrata aparte de la cuenta. Pregunta explícitamente por "TPV virtual" o "comercio electrónico", no por el datáfono físico.
2. El número de comercio (FUC). Son los nueve dígitos que identifican a tu comercio en Redsys. Aparece a veces como "código de comercio" o "MerchantCode".
3. El número de terminal. Normalmente es 001, pero puede haber varios terminales por comercio (por ejemplo, uno para pagos normales y otro para suscripciones).
4. La clave secreta de cifrado. La famosa "clave SHA-256" o "clave de comercio". Es la pieza con la que se firman las operaciones. El banco te dará una para el entorno de pruebas y otra distinta para producción. No las confundas (te lo digo por experiencia).

Pide al cliente que te reenvíe el correo o PDF original del banco con estos datos. Y cuando copies la clave, hazlo a un editor de texto plano primero, para cazar espacios o saltos de línea invisibles que se cuelan al copiar de un PDF.

El módulo commerce_redsys

Para Drupal Commerce el módulo de referencia es commerce_redsys. Lo instalas con Composer, como debe ser:

composer require drupal/commerce_redsys
drush en commerce_redsys -y

El módulo implementa Redsys como un gateway de pago de Commerce, así que se integra de forma nativa con el sistema de pasarelas (commerce_payment). Esto importa porque significa que el flujo de checkout, el estado de los pedidos y los registros de pago se gestionan con la maquinaria estándar de Commerce, no con un parche por fuera.

Configurar el gateway de pago

Una vez habilitado, vas a Commerce → Configuración → Pasarelas de pago (/admin/commerce/config/payment-gateways) y añades una nueva pasarela de tipo Redsys. Los campos que vas a rellenar son básicamente los datos del banco:

• Modo: Pruebas (test) o Producción (live). Empieza siempre en pruebas.
• Número de comercio (MerchantCode / FUC): tus nueve dígitos.
• Terminal: normalmente 001.
• Clave secreta de cifrado: la clave SHA-256 del entorno que corresponda.
• Moneda: EUR (978 en el código interno de Redsys).
• Tipo de transacción: autorización (0) para el caso habitual de cobro inmediato.

Guarda y asígnala al método de pago en tu flujo de checkout. Hasta aquí, lo aburrido. Ahora viene lo que de verdad da guerra.

Entorno de pruebas vs producción: dos URLs, dos claves

Redsys tiene dos entornos completamente separados y esto es fuente constante de quebraderos de cabeza:

• Pruebas: https://sis-t.redsys.es/sis/realizarPago
• Producción: https://sis.redsys.es/sis/realizarPago

Fíjate en la -t de la URL de test. La clave de cifrado de pruebas no funciona en producción y viceversa. Si ves que en local todo va perfecto y al pasar a producción empieza a fallar la firma, lo primero que tienes que comprobar es que estás usando la clave de producción y no te has dejado la de test puesta. Es, de lejos, el error más repetido.

Para probar en el entorno de test, Redsys publica tarjetas de prueba. La más usada es la 4548 8120 4940 0004, con fecha de caducidad cualquiera futura y un CVV de prueba. En el entorno de pruebas, además, te suele pedir un código de autenticación que viene documentado en el propio panel de pruebas de Redsys. Con esa tarjeta puedes simular pagos aprobados y denegados según los importes, lo que va de maravilla para validar que tu callback maneja bien los dos casos.

La firma HMAC SHA-256 y por qué te va a dar errores

El corazón de la integración con Redsys es la firma. Cada petición que envías y cada respuesta que recibes lleva una firma que garantiza que los datos no se han manipulado. El algoritmo es HMAC SHA-256, y el proceso, resumido, es así:

1. Se construye un objeto JSON con los parámetros de la operación (Ds_Merchant_Amount, Ds_Merchant_Order, Ds_Merchant_MerchantCode, Ds_Merchant_Currency, Ds_Merchant_Terminal, Ds_Merchant_TransactionType, la URL de notificación, etc.).
2. Ese JSON se codifica en Base64 y se envía en el parámetro Ds_MerchantParameters.
3. La clave del comercio se diversifica con el número de pedido (Ds_Merchant_Order) usando 3DES, y con esa clave derivada se calcula el HMAC SHA-256 de los parámetros. El resultado va en Ds_Signature.
4. Se indica el tipo de firma en Ds_SignatureVersion, que hoy es HMAC_SHA256_V1.

El módulo commerce_redsys se encarga de todo esto, pero conviene entenderlo porque cuando algo falla, falla aquí. El error estrella es el SIS0042: error en el cálculo de la firma (HASH). Las causas, por orden de frecuencia:

• Clave de cifrado mal copiada (espacios, saltos de línea) o estás usando la de test en producción.
• El número de pedido (Ds_Merchant_Order) no cumple el formato que exige Redsys: entre 4 y 12 caracteres, los cuatro primeros obligatoriamente numéricos. Si tu generador de pedidos saca un identificador que empieza por letra, la firma se valida pero Redsys lo rechaza.
• Desajuste de codificación al construir o leer el Base64.

Cuando te salga un SIS0042, no asumas que es un bug del módulo. El 95% de las veces es la clave o el formato del pedido.

La notificación online: el callback que te salva los pagos

Este es el punto que más gente olvida y el que más pedidos fantasma genera. Redsys no se fía de que el navegador del cliente vuelva a tu tienda para confirmar el pago, y hace bien: el cliente puede pagar y cerrar la pestaña antes de que le redirija de vuelta. Si tu sistema solo confirma el pedido cuando el cliente regresa a la URL de éxito, vas a tener cobros sin pedido confirmado.

La solución es la notificación online (lo que en otros sistemas se llama IPN o webhook). Redsys hace una petición servidor a servidor a una URL tuya, de forma independiente al navegador, comunicando el resultado de la operación. El parámetro que la define es Ds_Merchant_MerchantURL, y el módulo commerce_redsys expone una ruta para recibirla.

Tres cosas que tienes que vigilar con el callback:

• Que sea accesible públicamente y por HTTPS. Si estás en local con un entorno que el banco no puede alcanzar (un localhost o una IP privada), la notificación nunca llega. Para probar de verdad necesitas un dominio accesible o un túnel.
• Que valides la firma de la notificación. La respuesta de Redsys también viene firmada con HMAC SHA-256. El módulo lo comprueba, pero si has tocado algo, verifica que Ds_Response se lee de los parámetros decodificados y no de otro sitio.
• Que no te lo bloquee nada por delante. Un firewall de aplicación, un Cloudflare con reglas agresivas o un módulo de protección anti-bots pueden tumbar la petición de Redsys. Mete la ruta del callback en la lista de excepciones.

Un código Ds_Response entre 0000 y 0099 significa transacción autorizada. Cualquier otro valor es un rechazo o un error, y tu lógica debe dejar el pedido en el estado correcto en cada caso.

Activar Bizum dentro de la misma integración

Como decía al principio, Bizum no es una integración nueva. Una vez tienes Redsys funcionando, el proceso es:

1. Activar Bizum en el panel de Redsys (o pedírselo al banco). Hasta que tu comercio no tenga Bizum habilitado en el lado del banco, no podrás usarlo aunque lo configures en Drupal.
2. Habilitar el método Bizum en el módulo. En la configuración del gateway, commerce_redsys permite indicar que se ofrezca Bizum como método de pago. Por debajo, esto envía el parámetro Ds_Merchant_PayMethods con el valor que corresponde a Bizum (z), de modo que en la pantalla de pago de Redsys aparece la opción de pagar con Bizum además de con tarjeta.
3. Probarlo en el entorno de test, que también soporta operaciones Bizum simuladas.

La gracia es que conciliación, estados de pedido y notificación funcionan igual que con tarjeta, porque sigue siendo Redsys. No tienes un segundo sistema que cuadrar.

Pruebas de extremo a extremo y conciliación

Antes de dar por buena la integración, haz un recorrido completo en el entorno de pruebas: pago con tarjeta aprobado, pago con tarjeta denegado, pago con Bizum, y un caso de "cierro el navegador justo después de pagar" para confirmar que el callback deja el pedido bien.

Para la conciliación, contrasta tres fuentes: los pedidos en Commerce, las transacciones en el panel de Redsys y los abonos reales en la cuenta del banco. Cuando empieces en producción, revisa los primeros días que los importes cuadran y que no hay pedidos en estado "pendiente" que en realidad sí se cobraron. Ese desajuste casi siempre apunta a un problema con la notificación online.

¿Redsys o Stripe/PayPal? Cuándo merece la pena

No siempre Redsys es la mejor opción, aunque para España suela serlo. La diferencia gorda son las comisiones y la relación bancaria. Con Redsys, las comisiones por transacción las negocias con tu banco y suelen ser bastante más bajas que las de Stripe o PayPal, sobre todo si manejas volumen y tienes capacidad de negociar. El dinero, además, va directo a tu cuenta del banco.

A cambio, la integración es más áspera, el soporte pasa por el banco (que no siempre sabe de comercio electrónico) y la experiencia de configuración es la que es. Stripe o PayPal se montan en una tarde, tienen documentación excelente y APIs modernas, pero te cobran más por operación y, en el caso de algunos perfiles de cliente español, transmiten menos confianza que el TPV de toda la vida del banco.

Mi regla práctica: para una tienda española con cierto volumen que ya trabaja con un banco nacional, Redsys con Bizum es lo natural y lo más rentable. Para un proyecto internacional, un MVP que quieres lanzar rápido o un cliente que prioriza la facilidad sobre la comisión, Stripe o PayPal tienen todo el sentido. Y nada impide ofrecer Redsys/Bizum para el cliente nacional y una pasarela internacional en paralelo.

Si estás dándole vueltas a qué pasarela montar en tu proyecto o tienes una integración de Redsys que se resiste, hablemos de tu tienda online.

Activar Redsys y Bizum sin sustos

Repasa esta lista corta antes de pasar a producción y te ahorras la mayoría de los disgustos:

• Clave de cifrado de producción copiada sin espacios ni saltos de línea.
• URL apuntando a sis.redsys.es, no a sis-t.redsys.es.
• Número de pedido con formato válido (4-12 caracteres, los cuatro primeros numéricos).
• Notificación online accesible por HTTPS y no bloqueada por firewall ni Cloudflare.
• Bizum activado tanto en el panel de Redsys como en el módulo.
• Recorrido completo de pruebas hecho: aprobado, denegado, Bizum y abandono de navegador.
• Conciliación de los primeros pedidos reales contra el panel de Redsys y la cuenta del banco.

Con eso cubierto, la integración aguanta. Y cuando aparezca el inevitable SIS00xx en producción, ya sabes que la respuesta casi siempre está en la clave o en el formato del pedido, no en el módulo.