Integrar Redsys en .NET con tarjeta y Bizum: backend + formulario real

En este tutorial vas a montar una integración real y funcional de Redsys en .NET para:

1. Pago con tarjeta.
2. Pago con Bizum.

Incluye:

1. Formulario frontend.
2. Backend que firma Ds_MerchantParameters.
3. Redirección al TPV Redsys.
4. URL OK / URL KO.
5. Notificación online (MerchantURL) con validación de firma.

Actualizado: 20 de febrero de 2026.

¿Es viable hacerlo en .NET?

Sí, totalmente viable.

Conclusión técnica (basada en documentación oficial de Redsys):

1. El flujo de redirección es HTTP estándar (POST con Ds_SignatureVersion, Ds_MerchantParameters, Ds_Signature).
2. La firma HMAC_SHA512_V2 se puede implementar en .NET sin dependencias raras.
3. Bizum en redirección se activa con DS_MERCHANT_PAYMETHODS = z.

Por tanto, no hace falta cambiar a otra tecnología para este caso.

Proyecto de ejemplo en GitHub

Puedes clonar el proyecto desde:

https://github.com/davidcantonnadales/servidor-backend-redsys-tarjeta-bizum

Estructura principal:

1. RedsysBizumDemo.Web: aplicación MVC con formulario y callbacks.
2. RedsysBizumDemo.Tests: test de firma contra vector oficial de Redsys.

Flujo real de pago (tarjeta/Bizum)

El circuito completo implementado es:

1. Usuario rellena formulario de pago.
2. Pulsa botón Tarjeta o Bizum.
3. Backend construye parámetros DS_MERCHANT_*.
4. Backend firma y genera formulario auto-submit a Redsys.
5. Usuario paga en Redsys.
6. Redsys envía:
   • notificación server-to-server a MerchantURL
   • redirección navegador a URLOK o URLKO
7. Backend valida firma en ambos canales y decide estado final.

Parámetros clave que usa el ejemplo

1. DS_MERCHANT_AMOUNT: importe en céntimos.
2. DS_MERCHANT_ORDER: pedido (máx 12 chars, empieza por 4 dígitos).
3. DS_MERCHANT_MERCHANTCODE: FUC.
4. DS_MERCHANT_TERMINAL: terminal.
5. DS_MERCHANT_TRANSACTIONTYPE: 0 (autorización).
6. DS_MERCHANT_CURRENCY: 978 (EUR).
7. DS_MERCHANT_MERCHANTURL: callback online.
8. DS_MERCHANT_URLOK y DS_MERCHANT_URLKO: retorno navegador.
9. DS_MERCHANT_PAYMETHODS = z para forzar Bizum.

Paso 1: ejecutar el proyecto

git clone https://github.com/davidcantonnadales/servidor-backend-redsys-tarjeta-bizum.git
cd servidor-backend-redsys-tarjeta-bizum/solucion
dotnet restore
dotnet build -c Release
dotnet run --project RedsysBizumDemo.Web/RedsysBizumDemo.Web.csproj

Abre:

https://localhost:7206

Paso 2: configurar callback público (imprescindible)

Redsys no puede llamar a localhost desde internet. Necesitas URL pública:

1. Dominio real.
2. O túnel temporal (ngrok).

Ejemplo rápido:

ngrok http 5277

Después, actualiza:

Redsys:NotificationBaseUrl en RedsysBizumDemo.Web/appsettings.json
con la URL pública (normalmente HTTPS) de ngrok.

Paso 3: probar pago con tarjeta (sandbox)

Credenciales de prueba oficiales usadas en el ejemplo:

1. FUC: 999008881
2. Terminal: 001
3. Moneda: 978

Tarjeta de prueba (entorno test):

1. Número: 4548810000000003
2. Caducidad: 12/49
3. CVV: 123

Paso 4: probar Bizum (sandbox)

En el mismo formulario, pulsa Pagar con Bizum (envía DS_MERCHANT_PAYMETHODS=z).

Usuario demo Bizum de Redsys:

1. Usuario: 000000034
2. Contraseña: 1111

Implementación de firma en el ejemplo (.NET)

En RedsysBizumDemo.Web/Services/RedsysSignature.cs:

1. Se diversifica clave con AES-CBC e IV de ceros.
2. Se genera clave de operación en Base64.
3. Ese valor Base64 de la clave diversificada se usa como clave de HMAC.
4. Se calcula HMAC SHA-512 de Ds_MerchantParameters.
5. Se transforma a Base64URL para Ds_Signature.

Además, el proyecto incluye verificación de firma en:

1. POST /payments/notification
2. GET/POST /payments/result/ok
3. GET/POST /payments/result/ko

Prueba anti-regresión (sin suposiciones)

El test RedsysBizumDemo.Tests/UnitTest1.cs valida la firma con un vector oficial publicado por Redsys.

Ejecuta:

dotnet test -c Release

Si este test falla, no subas a producción.

Qué valida el backend para aceptar un pago

Regla de este ejemplo:

1. Firma válida (Ds_Signature correcta).
2. Ds_Response en rango autorizado (0..99).

Ese estado se guarda en memoria y se muestra en la home.

Errores reales típicos (y cómo evitarlos)

1. MerchantURL inaccesible desde internet: no llegan notificaciones.
2. Firma incorrecta: siempre validar Base64URL, pedido y clave.
3. Pedido inválido: Redsys exige formato concreto.
4. Bizum no activo en terminal: aunque envíes z, no funcionará sin activación contractual.

Checklist para pasar a producción

1. Cambiar UseSandbox=false.
2. Usar FUC/terminal/clave reales.
3. Configurar URLs HTTPS reales.
4. Persistir pagos en base de datos (no en memoria).
5. Añadir idempotencia en notificación online.
6. Registrar trazas seguras sin exponer datos sensibles.

Fuentes oficiales utilizadas

1. Firmar operación (HMAC SHA512 V2)
2. Realizar pago por redirección
3. Operativa Bizum
4. Parámetros de entrada/salida
5. Tarjetas y entornos de prueba

Conclusión

Integrar Redsys con tarjeta y Bizum en .NET es viable y sólido si respetas tres reglas:

1. Firma exacta según especificación.
2. Callback online público y verificable.
3. Validación estricta de Ds_Response y firma antes de marcar pedido como pagado.