Redsys y Bizum: cobrar con la pasarela de tu banco

Qué es Redsys en realidad y qué implica cobrar por ahí

Redsys no es un proveedor que contratas por internet en diez minutos. Es la plataforma que usan la mayoría de bancos españoles para su TPV Virtual, y lo que tú contratas es el TPV con tu banco. De ahí salen tres datos: el código de comercio (FUC), el terminal y una clave secreta de firma. Con eso se firman las peticiones. La consecuencia práctica es que el banco es tu interlocutor para todo lo que no sea código: tarifas, alta de Bizum, credenciales adicionales, incidencias con un cobro concreto. Y que el panel del TPV Virtual es la única fuente de verdad sobre qué se ha cobrado, cosa que condiciona bastante el diseño de la integración.

• Las credenciales las da el banco, no se autogeneran desde un panel de desarrollador.
• La integración habitual es por redirección: el cliente sale a la página del banco y vuelve.
• Muchas operaciones (devoluciones, consultas de cargos) viven en el TPV Virtual, no en una API.

Bizum es el mismo TPV cambiando una letra, pero se contrata aparte

Técnicamente Bizum no es otra integración: es el mismo formulario firmado indicando otro método de pago. Eso lleva a un error muy caro de soporte: dar por hecho que si la tienda tiene Redsys, tiene Bizum. Falso. Bizum se contrata con el banco y se activa sobre tu terminal. Si el botón se deduce del proveedor, el cliente lo pulsa, el TPV le rechaza la operación y le enseña un error del banco que tú no puedes explicar. Por eso los métodos que se muestran en la tienda son una lista declarada explícitamente en la configuración. Si está vacía, no se enseña ningún sello. Preferimos un checkout que enseñe de menos a uno que prometa lo que el banco no tiene activo.

• Que el TPV sea Redsys no garantiza que el banco tenga Bizum activo sobre ese terminal.
• La elección del cliente entre tarjeta y Bizum viaja explícita en el contrato de checkout: si una capa intermedia no la reenvía, todo se cobra por tarjeta sin dar ningún error.
• El selector de Bizum solo aparece cuando la pasarela real de la tienda es Redsys.

Por qué Bizum convierte carritos que se abandonarían

El abandono en el momento del pago tiene causas conocidas y una es puramente física: teclear dieciséis dígitos, caducidad y CVV en un móvil, y a veces además esperar la autenticación del banco. Bizum sustituye eso por el teléfono y la confirmación en la app bancaria. También quita fricción psicológica: hay compradores que no dejan la tarjeta en una tienda pequeña que no conocen y en cambio sí pagan por un canal que asocian a su banco. No voy a darte un porcentaje de mejora porque cualquier cifra que te dé sin medir tu tienda sería inventada. Lo que sí digo es dónde está la palanca: menos campos, menos salida de la app, menos motivos para dejarlo.

Cómo se firma la petición y por qué el importe se recalcula en el servidor

La petición se envía como un formulario con los parámetros del pago codificados y una firma calculada con la clave secreta del banco. Esa firma se calcula siempre en el servidor: si la clave tocara el navegador, cualquiera podría firmar el importe que quisiera. El importe que se firma no sale del carrito del cliente, sale del total congelado al crear el pedido en servidor. Y cuando llega la confirmación, el importe notificado se compara otra vez contra ese total antes de marcar nada como pagado. Firmado por el banco no significa correcto para tu pedido: puede ser un formulario viejo reabierto o una notificación válida de otro importe.

• El paso a pagado corre entero dentro de una transacción: leer el pedido, salir si ya estaba pagado, rechazar estados que no toquen, comparar importe y solo entonces mover el stock de reservado a vendido.
• El uso del cupón se contabiliza en ese momento y no al crear el pedido: si no, los checkouts abandonados agotan un cupón con usos limitados.
• Confirmar stock fuera de esa transacción es la vía directa a descontar dos veces la misma unidad.

La notificación del banco es la única confirmación válida

Cuando el cliente vuelve a tu página de éxito, el pedido casi nunca está confirmado todavía. El retorno del navegador y la notificación servidor a servidor son canales distintos, y el segundo puede tardar segundos. Si pintas pedido confirmado con el retorno, mientes. Si pintas estamos confirmando tu pago y la notificación se retrasa, dejas al cliente clavado en un spinner sin saber si le han cobrado. La solución es honesta y sencilla: la página del pedido se refresca sola mientras está pendiente, durante el primer minuto y medio pide no cerrar la ventana, y a partir de ahí libera al cliente diciéndole que puede irse y recibirá el email cuando se procese. La cancelación lleva su propio parámetro en la URL para mostrar el mensaje real: no se te ha cobrado nada, tu carrito sigue aquí.

Redsys no reintenta la notificación: el fallo más caro es el que no deja rastro

Aquí está la diferencia grande con las pasarelas internacionales. Si devuelves un error a un webhook de Stripe, el proveedor reintenta durante horas. Redsys manda la notificación a la URL que va firmada en la petición y, si tu handler revienta por un tiempo de espera de base de datos o un despliegue a medias, esa confirmación no vuelve nunca. El cliente tiene el cargo en la tarjeta y tú tienes un pedido pendiente que el cron acabará caducando. Nadie se entera hasta que el cliente reclama. Por eso hay dos redes, y ninguna sobra.

• Aviso en caliente: si falla el procesado de una notificación firmada de verdad por el banco, sale un email inmediato al dueño para que compruebe en el TPV Virtual si el cobro existe.
• Nunca se alerta por firma inválida. El endpoint es público y sin autenticar, tiene que serlo porque lo llama el banco, así que cualquiera puede lanzarle basura. Alertar por eso entrena al dueño para ignorar justo el email que importa. Firma mala: aviso en el log y respuesta de error, sin correo.
• Revisión diaria: como no hay forma de listar los cargos de Redsys por API, se busca por la huella propia. Al generar el formulario se sella la marca de inicio de pago; el trabajo nocturno saca los pedidos caducados que la tienen, con su importe, para buscarlos en el panel del banco.

Trampas del minado que dejan la tienda cobrando en el aire

Casi todas se manifiestan como algo que parece funcionar. Esa es la parte peligrosa. La notificación puede llegarte como formulario codificado o ya convertida en objeto según quién la haya parseado antes por el camino, así que se normaliza sobre el cuerpo original antes de verificar la firma; asumir un formato es un fallo que en local no reproduces. La URL de notificación viaja dentro de la petición firmada, no en un panel, así que si falta la variable de entorno el cliente paga, el banco cobra y la confirmación se manda a ninguna parte: por eso hay un candado que impide arrancar el pago si no está configurada. Mejor perder una venta que cobrarla sin poder confirmarla.

• El número de operación tiene doce caracteres con los cuatro primeros numéricos, así que no cabe un id de base de datos. La correlación va en el campo libre de datos del comercio y el número se genera determinista repartiendo toda la entropía del id, para que un doble envío del formulario no abra dos operaciones.
• El pago denegado se registra pero no marca el pedido como fallido: eso liberaría el stock y rompería el reintento del cliente que se equivocó de CVV.
• Un pago que entra sobre un pedido ya cancelado o reembolsado no se revive: se avisa al dueño con el importe y la referencia por si procede devolverlo.
• El campo de la clave secreta es de tipo contraseña y el navegador lo autorrellena sin avisar, pisando la clave real del banco. Se resuelve no renderizando un campo editable si ya hay clave, leyendo los secretos del estado y validando el formato antes de guardar.
• El terminal con un uno de ejemplo en gris se guarda vacío y el TPV queda sin conectar. Va como valor real por defecto, no como texto de ayuda.
• El entorno no puede ser un campo libre que alguien olvide en pruebas: con Redsys siempre es el TPV real, y así queda forzado al guardar.
• El nombre de comercio y el concepto se sanean a un juego de caracteres limitado y a su longitud máxima, porque un acento o una almohadilla hacen que la pasarela devuelva un error de formato en vez de la página de pago.

Los efectos posteriores al cobro se marcan uno a uno

Email de confirmación, alta en el ERP, puntos de fidelidad. Si los cuelgas del primer procesado de la notificación y el pago se marcó pero el email falló, el cliente paga y no recibe nada. Si los ejecutas en cada notificación, mandas el email tres veces. Cada efecto lleva su propia marca en el pedido: el email se sella solo cuando el envío devuelve correcto, los puntos son idempotentes por su propio registro y los envíos al ERP fallidos los reintenta el trabajo nocturno. Ninguno de estos efectos puede tumbar la respuesta a la notificación: el dinero ya está cobrado y devolver un error por un email caído solo empeora las cosas. La revisión diaria busca además pedidos pagados sin email confirmado como anomalía.

Preguntas frecuentes