Redsys: pasarela de pago de la tienda y de Fidelización

Redsys es el TPV virtual de los bancos españoles con el que Connect Manager cobra online en la tienda del delivery propio y en Fidelización: pedidos, tarjetas regalo, cuotas de socio, entradas de la agenda del club y pagos de eventos. El dinero va directo a la cuenta del comercio del cliente; Connect Manager prepara el pago, recibe la confirmación firmada del banco y hace lo que toca después, como meter el pedido cobrado en Ágora o emitir allí la factura de anticipo de un evento. Este manual es para el técnico que configura el TPV virtual de un cliente: qué datos pedir al banco, dónde ponerlos según lo que se cobre, cómo probar y qué hacer cuando un pago no cuadra.

Qué hace la integración#

• Cobra con tarjeta en el comercio de Redsys del propio cliente, con su código de comercio (FUC), su terminal y su clave secreta SHA-256. El dinero no pasa por FOS.

• Pedidos de la tienda online: un TPV por local. Si el banco los tiene activos en el terminal, el cliente puede elegir también Bizum o Apple Pay / Google Pay antes de ir al banco.

• Tarjetas regalo de la tienda online: cobra el TPV del local que vende cada tarjeta.

• Tarjetas regalo del club, cuotas de socio (alta y renovación) y entradas de la agenda del club: un TPV para todo el grupo.

• Pagos de las ofertas de eventos: el TPV de cada local emisor; al conciliar el cobro se emite la factura de anticipo en Ágora.

• Entorno de pruebas o de producción en cada comercio, para probar sin mover dinero.

• Solo da un pago por bueno con la notificación firmada que Redsys manda de servidor a servidor: comprueba la firma con las credenciales que se usaron para ese pago (guardadas con el pago, así que cambiar la clave no rompe los pagos en curso), toma el importe del dato firmado por el banco y no repite nada si Redsys reintenta el aviso.

• Evita cobrar dos veces: si el cliente vuelve atrás o abre otra pestaña con el mismo importe, se reutiliza el mismo número de pedido y el banco rechaza el repetido.

• Guarda la respuesta del banco para conciliar: código de respuesta y de autorización con cada pago. En los pedidos de la tienda y en las entradas se guarda solo una lista cerrada de datos (fecha, número de pedido, importe, respuesta, autorización, marca y país de la tarjeta) con la tarjeta enmascarada a sus cuatro últimas cifras.

• Devuelve al cliente a una pantalla de resultado con un enlace firmado que caduca a las 4 horas; esa pantalla lee el estado real del pago, no lo que diga el enlace.

Qué no hace#

• No devuelve dinero: las devoluciones se hacen en el panel de Redsys. Cancelar un pedido, una tarjeta regalo, una membresía o una entrada en Connect Manager no reembolsa el cargo.

• No cobra cuotas recurrentes de forma automática ni guarda tarjetas: cada renovación la paga el socio.

• No recarga monederos del club con tarjeta desde la web.

• Bizum y Apple Pay / Google Pay solo se eligen en los pedidos de la tienda online; en el resto se abre la página de pago estándar de Redsys.

• No se entera de las devoluciones o anulaciones hechas en el panel de Redsys.

• No trabaja con otras pasarelas de pago.

Requisitos#

• Un TPV virtual de Redsys contratado por el cliente con su banco, con firma SHA-256: uno por local para la tienda online, uno de grupo para Fidelización y uno por local emisor para eventos (pueden ser el mismo comercio si el banco lo permite).

• Las credenciales de pruebas y las de producción: la clave de pruebas y la real son distintas.

• Si se quieren en la tienda, Bizum y Apple Pay / Google Pay activados por el banco en ese terminal.

• Que el terminal tenga activada la notificación online (por HTTP): Connect Manager manda en cada pago la dirección a la que Redsys debe avisar.

• En Ágora, la forma de pago con la que deben entrar los cobros online (pedidos y anticipos de eventos).

• Permisos en Connect Manager: Delivery: Configurar locales para la tienda; además Fidelización: Añadir saldo para las tarjetas regalo de la tienda; Fidelización: Activar por grupo para el TPV del grupo; Fidelización: Configurar eventos para los locales de eventos.

• Quién hace qué: el cliente contrata el TPV y consigue sus datos del banco; el distribuidor los pone en Connect Manager y hace la prueba; FOS mantiene la plataforma, que es la que recibe las notificaciones.

Datos que necesitamos#

Dónde se configura cada TPV#

Configuración paso a paso#

En el banco (Redsys)#

1. Pide al banco el TPV virtual con firma SHA-256 y anota FUC, terminal y clave, de pruebas y de producción.

2. Si el cliente quiere Bizum o Apple Pay / Google Pay en la tienda, pide que los activen en ese terminal.

3. Confirma con el banco que el terminal tiene la notificación online activada. No hace falta escribir ninguna dirección en Redsys: Connect Manager la manda en cada pago.

En Connect Manager: pedidos de la tienda online#

1. Ve a Configuración → Locales, abre el local y entra en Pasarela de pago.

2. Enciende Cobrar por la pasarela.

3. Elige el Entorno: «Pruebas» (el valor por defecto) o «Producción (cobra de verdad)». Al cambiar el entorno a Pruebas, los campos que estén vacíos se rellenan solos con el comercio de demostración público de Redsys.

4. Rellena Código de comercio (FUC), Terminal y Clave secreta (SHA-256). La clave se guarda cifrada y no se vuelve a enseñar: el campo vacío significa «no la cambies».

5. Enciende Bizum y Apple Pay y Google Pay solo si el banco los tiene activos en el terminal.

6. Pulsa Guardar. En el listado de locales, la columna «Cobro» indica si el local cobra y en qué entorno.

7. En Reparto, Recogida y En mesa, revisa la Forma de pago de Ágora con la que entran los pedidos pagados online.

En Connect Manager: tarjetas regalo de la tienda online#

1. El grupo tiene que tener configurado su club de fidelización (el saldo de la tarjeta vive en el monedero del club).

2. Ve a Configuración → Tienda pública → Tarjetas regalo y enciende Vender tarjetas regalo.

3. Crea cada tarjeta con su Título, el Local que la vende (solo salen los locales que pueden cobrar; en la plataforma real, solo los que tienen la pasarela en producción) y su importe fijo o libre.

4. Guarda. Si después cambian los datos de la pasarela de ese local, la tarjeta deja de venderse hasta que alguien con permiso para añadir saldo vuelva a guardar esta pantalla.

En Connect Manager: TPV del grupo (tarjetas regalo del club, socios y entradas)#

1. En /fidelizacion, ve a Configuración → Portal público de clientes, abre el grupo y entra en Tarjetas regalo.

2. En «TPV virtual del grupo (Redsys)», rellena Código de comercio (FUC), Terminal y Clave secreta (SHA-256), y elige el Entorno («Pruebas» o «Producción»; vacío, el global de la plataforma).

3. Guarda. Ese mismo TPV cobra las tarjetas regalo del club, las cuotas de socio (Configuración → Configuración de socios) y las entradas de la agenda (Socios → Agenda).

[!WARNING] Las tarjetas regalo y el alta de socios tienen un «modo demostración» que simula el pago sin banco y solo funciona mientras el grupo no tiene TPV configurado. La tienda de tarjetas regalo en demostración solo la ve quien ha entrado en el panel del club; el alta de socios en demostración, no. Apágalo en cuanto termines de enseñarlo: un pago simulado da saldo o membresía reales.

En Connect Manager: pagos de eventos#

1. En /fidelizacion, ve a Configuración → Configuración de eventos → Locales y abre el local emisor (rol emisora o ambos).

2. En «Pago online (Redsys)»: Aceptar pagos con tarjeta (Redsys) (encendido por defecto; apagarlo quita el botón de pago sin borrar las credenciales), Código de comercio (FUC), Terminal y Clave secreta (SHA-256) (vacía, se mantiene la guardada; «Quitar la clave guardada» la borra).

3. Entorno del TPV: «Pruebas (sin cargos reales)» o «Producción (cobros reales)»; vacío, el global de la plataforma. Usa las credenciales del entorno elegido.

4. Forma de pago (cobros por pasarela): la forma de pago de Ágora con la que se factura el anticipo cuando el cliente paga con tarjeta; sin ella se usa la de transferencia.

Cómo funciona#

El recorrido de un pago#

Cuando el cliente pulsa pagar, Connect Manager crea un intento de pago con un número de pedido propio (cuatro cifras y seis letras o números) y guarda con él las credenciales del comercio. Con ellas firma un formulario con el importe, el número de pedido, el nombre del comercio, la dirección de notificación y las direcciones de vuelta, y el navegador del cliente lo envía a la página de pago de Redsys. El cliente paga allí (con la autenticación de su banco). Redsys avisa entonces a Connect Manager de servidor a servidor: se comprueba la firma con las credenciales guardadas en el intento, se toma el importe firmado por el banco y, bajo bloqueo para que un aviso repetido no haga nada dos veces, se marca el pago como cobrado y se lanza lo que toca. Por último Redsys devuelve al cliente a la pantalla de resultado, que lee el estado real del pago.

sequenceDiagram
    participant C as Cliente
    participant H as Connect Manager
    participant R as Redsys
    participant A as Ágora
    C->>H: Pagar
    H->>H: Intento con número de pedido y credenciales guardadas
    H-->>C: Formulario firmado con importe y direcciones
    C->>R: Envía el formulario y paga
    R->>H: Notificación firmada servidor a servidor
    H->>H: Verifica la firma y lee el importe firmado
    H->>H: Marca cobrado una sola vez
    H->>A: Pedido cobrado o factura de anticipo, según el caso
    R-->>C: Vuelta a la pantalla de resultado
    C->>H: Resultado con el estado real

Qué pasa al confirmar el pago#

Las direcciones de notificación#

Cada tipo de pago tiene su dirección en https://hub.connectmanager.es, y viaja dentro de cada pago: no hay que escribirlas en Redsys.

• Pedidos de la tienda: /api/delivery/redsys/notification

• Tarjetas regalo (club y tienda): /api/loyalty/gift-cards/redsys/notification

• Cuotas de socio: /api/loyalty/memberships/redsys/notification

• Entradas de la agenda: /api/loyalty/club-events/redsys/notification

• Pagos de eventos: /api/loyalty/events/redsys/notification

La de pedidos contesta siempre «OK» o «KO» con un código 200 para que Redsys no reintente lo que ya está decidido; las de Fidelización contestan con un error 400 cuando la firma no es válida o el pago no existe.

Casos raros que se protegen#

• Tarjeta denegada o pago abandonado: no se confirma nada y el cliente puede reintentar. En los pedidos de la tienda, los intentos que se van al banco y no vuelven en 20 minutos se marcan como caducados, y si el banco confirma tarde el pago se da por bueno igual.

• El banco cobra un importe distinto: un pedido cobrado de menos no se manda a la cocina y queda como incidencia (cobrado de más, entra y queda anotado para devolver la diferencia); una tarjeta regalo o una cuota con importe distinto no se entrega ni se activa sola; un sobrepago de un evento queda en Conciliación para decidir.

• Cobro sobre algo cancelado (un pedido, una tarjeta regalo o una oferta de evento cancelada o caducada) o segundo cobro de un pedido que ya está en marcha: no se aplica solo y queda registrado para devolverlo desde Redsys.

• Pagos de pruebas: en eventos se marcan con [TEST] en Conciliación; una tarjeta regalo de la tienda pagada en el entorno de pruebas no se entrega en la plataforma real, porque el saldo sería real.

Comprobar que funciona#

1. Con el comercio en Pruebas, haz un pago real de punta a punta con la tarjeta de prueba que publica Redsys en su documentación: un pedido de la tienda, una tarjeta regalo, un alta de socio, una entrada o un vencimiento de evento, según lo que vaya a usar el cliente.

2. Comprueba que la pantalla de resultado dice que el pago está hecho y que la consecuencia ocurre: el pedido llega a «En el TPV», la tarjeta se entrega, la membresía se activa, llegan las entradas o el cobro aparece conciliado en Eventos.

3. En el panel de pruebas de Redsys, busca la operación por su número de pedido y mira que la notificación se entregó bien.

4. Haz un pago denegado o abandónalo en la página del banco: no debe confirmarse nada.

5. Cambia a Producción con las credenciales reales, haz un cobro pequeño, compruébalo y devuélvelo desde el panel de Redsys.

Errores frecuentes y solución#

Preguntas frecuentes#

¿Qué datos de Redsys necesito para cobrar online con Connect Manager y Ágora?#

El código de comercio (FUC), el terminal y la clave secreta SHA-256 del TPV virtual, de pruebas y de producción. Los da el banco del cliente.

¿Tengo que configurar la URL de notificación en el panel de Redsys?#

No. Connect Manager envía la dirección de notificación y las de vuelta dentro de cada pago. Lo que sí debe estar activo en el terminal es la notificación online.

¿Puedo usar un mismo TPV virtual para todos los locales?#

En la tienda online cada local tiene su pasarela, pero puedes poner los mismos datos en varios locales si el cliente cobra todo en un único comercio. En Fidelización hay un TPV para todo el grupo, y en eventos uno por local emisor.

¿Cómo devuelvo un pago hecho con Redsys?#

Desde el panel de Redsys, buscando la operación por su número de pedido. Cancelar en Connect Manager no devuelve el dinero.

¿Cómo pruebo sin cobrar de verdad?#

Pon el entorno en Pruebas, usa las credenciales de pruebas (en la tienda se rellenan solas las del comercio de demostración de Redsys) y paga con la tarjeta de prueba de Redsys.

¿Se puede pagar con Bizum en la tienda online?#

Sí, si el banco tiene Bizum activo en el terminal del local y enciendes la opción en su Pasarela de pago. Lo mismo para Apple Pay y Google Pay.

Referencias#

• Ficha de Redsys en el catálogo de integraciones

• Delivery propio: conectar la tienda online con Ágora

• Fidelización: conectar el club con Ágora

• Correo electrónico: proveedores de envío (los correos de tarjetas regalo, socios y entradas)

• Portal de desarrolladores de Redsys