Integrar Bizum en una Web o App: Redsys y Devoluciones

Para integrar Bizum en una web o app tienes que contratarlo con un banco que lo ofrezca y conectarte a su pasarela certificada. Si tu banco trabaja con el TPV Virtual de Redsys, basta con enviar el parámetro Ds_Merchant_PayMethods con el valor «z» en el formulario de pago por redirección. Lo montamos en el desarrollo de apps y webs con cobro integrado para empresas de Madrid.

Bizum mueve el dinero de cuenta a cuenta mediante transferencias inmediatas, así que el riesgo está en tu backend. Si confirmas un pedido antes de verificar la notificación firmada, sirves mercancía que nadie ha pagado. Si no tratas al cliente que abandona en la app de su banco, el pedido se queda pendiente sin que nadie lo cierre.

Al terminar sabrás qué vía de integración te conviene y cuándo Bizum complementa a las domiciliaciones SEPA en software a medida para cobros recurrentes.

Qué es Bizum y qué supone integrarlo en una web o app

Bizum es un método de pago de cuenta a cuenta basado en transferencias inmediatas que ofrecen los bancos españoles adheridos. En una compra online, el cliente introduce su número de móvil y acepta el pago en la app de su banco, que es quien valida la operación.

Para tu software, Bizum se comporta como un método de pago más del TPV: Redsys indica que recibes el cobro igual que si el cliente hubiera pagado con tarjeta, y el resultado llega en la misma notificación firmada.

Cómo integrar Bizum: Redsys o la pasarela de tu banco

Bizum se contrata siempre a través de un banco adherido, que te da acceso a una pasarela certificada. Las vías habituales son estas:

Módulo de pago del TPV Virtual: Redsys publica módulos para plataformas de comercio electrónico que ya incluyen Bizum. Encaja si tu tienda corre sobre una de esas plataformas.
Redirección a Redsys: tu servidor monta el formulario firmado con «z» y Redsys gestiona la autorización completa, según su documentación de Bizum para desarrolladores. Encaja en software a medida.
Pasarela de tu banco o de un proveedor de pagos: sirve si está certificada para Bizum. Pregunta a tu banco qué conexión te ofrece.

Las comisiones las negocias con tu banco, como se detalla al comparar qué pasarela de pago sale más barata. Si partes de cero, repasa qué es Redsys y cómo se conecta a tu web y los tipos de pasarelas de pago y su latencia.

Puente de luz cian que une un móvil holográfico flotante con una torre bancaria de cristal sobre un suelo espejado — Bizum siempre entra en tu web a través de la pasarela de un banco.

Flujo de un pago con Bizum en tu web o app

Un pago con Bizum por Redsys sigue estos pasos, y el último es responsabilidad de tu backend:

Botón: el cliente elige Bizum y tu servidor envía a Redsys el formulario firmado con importe y número de pedido.
Teléfono: el cliente introduce su móvil en la pantalla de Bizum. Puedes enviarlo relleno con DS_MERCHANT_BIZUM_MOBILENUMBER.
Validación: el cliente acepta en la app de su banco o con un código de un solo uso, según su entidad.
Notificación: Redsys llama a tu URL de notificación con los datos firmados y devuelve al cliente a tu página de éxito o error.
Confirmación: tu backend verifica la firma y solo entonces da el pedido por pagado.

En una app nativa, la redirección se abre en el navegador del sistema y la confirmación llega a tu servidor, igual que en una PWA instalada en el móvil del cliente. La regla es la misma que con Stripe, Apple Pay y Google Pay dentro de una app: el servidor decide si un pedido está pagado, nunca el móvil.

Secuencia de anillos holográficos turquesa que guían una esfera de luz desde un móvil hasta un servidor — El pedido solo cambia de estado cuando el servidor recibe la notificación.

Devoluciones y límites de Bizum para comercios

En Redsys, una devolución es una operación con Ds_Merchant_TransactionType 3, total o parcial, que el TPV acepta si la suma devuelta no supera el importe autorizado. Un Ds_Response 0900 confirma que se ha ejecutado. Redsys recomienda reservar la anulación para errores inmediatos, como un fallo de tu base de datos al validar el pedido. Pregunta a tu banco qué operativas admite tu terminal con Bizum.

Los límites de Bizum entre particulares no se aplican a los pagos en comercios: la respuesta de Bizum sobre límites en comercios aclara que Bizum no los fija, aunque cada banco puede poner los suyos. En el entorno de pruebas de Redsys, ninguna operación puede superar 10 euros.

Bizum encaja en pagos puntuales. Si cobras cuotas, la lógica de reintentos y avisos está en qué hacer cuando falla el cobro de una suscripción.

Sello holográfico hexagonal azul eléctrico que se ilumina en verde al encajar sobre un sobre de luz abstracta — La firma demuestra que la notificación viene de Redsys y no se ha tocado.

CodeZone Pro Tip: verifica la firma HMAC_SHA512_V2 de cada notificación de Redsys antes de marcar como pagado un pedido cobrado con Bizum.

const crypto = require("node:crypto");

// HMAC_SHA512_V2: la clave de cada operación es el número de pedido cifrado con AES-128-CBC e IV de ceros
function claveOperacion(claveTerminal, pedido) {
  const clave = Buffer.from(claveTerminal.slice(0, 16).padEnd(16, "0")); // 16 caracteres exactos
  const aes = crypto.createCipheriv("aes-128-cbc", clave, Buffer.alloc(16));
  return Buffer.concat([aes.update(pedido, "utf8"), aes.final()]).toString("base64");
}

function firmar(merchantParameters, claveTerminal, pedido) {
  // Se firma el Base64 tal como llega, sin descodificarlo
  return crypto.createHmac("sha512", claveOperacion(claveTerminal, pedido))
    .update(merchantParameters).digest("base64url");
}

function verificarNotificacion(body, claveTerminal) {
  const { Ds_MerchantParameters: params, Ds_Signature: firma, Ds_SignatureVersion: version } = body;
  if (version !== "HMAC_SHA512_V2") return { valida: false, motivo: "versión de firma inesperada" };
  const datos = JSON.parse(Buffer.from(params, "base64").toString("utf8"));
  const esperada = Buffer.from(firmar(params, claveTerminal, datos.Ds_Order));
  const recibida = Buffer.from(String(firma).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""));
  // Comparación en tiempo constante: no confirmes ningún pedido con una firma que no cuadra
  if (esperada.length !== recibida.length || !crypto.timingSafeEqual(esperada, recibida)) {
    return { valida: false, motivo: "firma incorrecta" };
  }
  const codigo = Number(datos.Ds_Response); // de 0000 a 0099, pago autorizado
  return { valida: true, pedido: datos.Ds_Order, pagado: codigo >= 0 && codigo <= 99,
    bizum: String(datos.Ds_ProcessedPayMethod) === "68" }; // 68 identifica Bizum
}

// Vector de prueba publicado por Redsys en su guía de firma
const ejemplo = "eyJEU19NRVJDSEFOVF9BTU9VTlQiOiI5OTkiLCJEU19NRVJDSEFOVF9PUkRFUiI6IjEyMzQ1Njc4OTAiLCJEU19NRVJDSEFOVF9NRVJDSEFOVENPREUiOiI5OTkwMDg4ODEiLCJEU19NRVJDSEFOVF9DVVJSRU5DWSI6Ijk3OCIsIkRTX01FUkNIQU5UX1RSQU5TQUNUSU9OVFlQRSI6IjAiLCJEU19NRVJDSEFOVF9URVJNSU5BTCI6IjEiLCJEU19NRVJDSEFOVF9NRVJDSEFOVFVSTCI6Imh0dHA6XC9cL3d3dy5wcnVlYmEuY29tXC91cmxOb3RpZmljYWNpb24ucGhwIiwiRFNfTUVSQ0hBTlRfVVJMT0siOiJodHRwOlwvXC93d3cucHJ1ZWJhLmNvbVwvdXJsT0sucGhwIiwiRFNfTUVSQ0hBTlRfVVJMS08iOiJodHRwOlwvXC93d3cucHJ1ZWJhLmNvbVwvdXJsS08ucGhwIn0";
console.log(firmar(ejemplo, "sq7HjrUOBfKmC576ILgskD5srU870gJ7", "1234567890").startsWith("Vjo02eSWq249")); // true
module.exports = { firmar, verificarNotificacion };

Con esta comprobación, una notificación manipulada o un pago denegado nunca llegan a almacén. El secreto de firma del terminal vive solo en el servidor, con las prácticas de seguridad en aplicaciones web según OWASP.

Lo Que Arriesgas Si Confirmas Pedidos Sin Verificar la Notificación

Si das un pedido por pagado porque el cliente llegó a tu página de éxito, cualquiera puede abrir esa dirección sin pagar. La notificación firmada es la única señal fiable de que Bizum autorizó el cobro.