Migración de algoritmo de notificaciones de SHA-1 a SHA-256

Esta guía te ayudará a migrar tu integración de notificaciones de Checkout desde el algoritmo SHA-1 (obsoleto) al algoritmo SHA-256 (recomendado y seguro).

¿Por qué migrar?

SHA-1 ha sido marcado como obsoleto debido a vulnerabilidades de seguridad descubiertas en los últimos años. SHA-256 es el estándar actual de la industria y proporciona un nivel de seguridad significativamente mayor para proteger la integridad de las notificaciones.

Diferencias entre SHA-1 y SHA-256

Estructura de la firma SHA-1 (Obsoleto)

{
  "status": { /* ... */ },
  "requestId": 1234,
  "reference": "TEST_123424",
  "signature": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s"
}

• La firma NO tiene prefijo
• Longitud: 40 caracteres hexadecimales
• Fórmula: SHA-1(requestId + status.status + status.date + secretKey)

Estructura de la firma SHA-256 (Recomendado)

{
  "status": { /* ... */ },
  "requestId": 1234,
  "reference": "TEST_123424",
  "signature": "sha256:a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"
}

• La firma TIENE el prefijo sha256:
• Longitud: 64 caracteres hexadecimales (sin contar el prefijo)
• Fórmula: SHA-256(requestId + status.status + status.date + secretKey)

Proceso de migración

Fase 1: Preparación (Soporte dual)

Durante esta fase, tu sistema debe soportar AMBOS algoritmos simultáneamente. Esto te permite realizar una transición sin interrupciones.

Actualizar el código de validación

Modifica tu código para detectar el algoritmo utilizado, a continuación mostramos algunos ejemplos de lo que puedes implementar pero la implemencación exacta dependerá del lenguaje de programación que uses y de la estructura de código que tengas. Esta implementación es meramente una referencia y no debe ser usada tal cual en producción sin antes adaptarla a tu contexto específico.

function validateSignature($notification, $secretKey) {
    $signature = $notification['signature'];
    $requestId = $notification['requestId'];
    $status = $notification['status']['status'];
    $date = $notification['status']['date'];
    
    // Identificar el algoritmo
    if (strpos($signature, 'sha256:') === 0) {
        // SHA-256
        $receivedSignature = substr($signature, 7); // Remover prefijo
        $generatedSignature = hash('sha256', $requestId . $status . $date . $secretKey);
    } else {
        // SHA-1 (legacy)
        $receivedSignature = $signature;
        $generatedSignature = sha1($requestId . $status . $date . $secretKey);
    }
    
    return hash_equals($generatedSignature, $receivedSignature);
}

Actualizar el código de validación si estás usando lightbox

Si estás usando Lightbox para integrar Placetopay, asegúrate de actualizar el código que maneja la notificación para soportar ambos algoritmos. Revisa la sección de Lightbox para más detalles sobre cómo manejar las notificaciones en este contexto.

Probar en ambiente de pruebas

1. Despliega el código actualizado en tu ambiente de desarrollo/staging
2. Solicita a soporte de Placetopay que habiliten SHA-256 en tu cuenta de pruebas
3. Realiza transacciones de prueba y verifica que las notificaciones se validen correctamente
4. Confirma que tanto SHA-1 como SHA-256 funcionan correctamente

** Monitorear y registrar (Opcional) **

Si quieres monitorear el proceso de migración de cerca, implementa logging para rastrear qué algoritmo se está usando. Por ejemplo en PHP podrías agregar:

if (strpos($signature, 'sha256:') === 0) {
    error_log("Notificación recibida con SHA-256 para requestId: {$requestId}");
} else {
    error_log("Notificación recibida con SHA-1 (legacy) para requestId: {$requestId}");
}

Fase 2: Activación de SHA-256

Una vez que tu código esté actualizado y probado:

1. Despliega tus cambios en producción
2. Contacta a soporte de Placetopay para solicitar la activación de SHA-256 en tu cuenta de producción
3. El equipo de Placetopay activará SHA-256 para tu cuenta
4. A partir de ese momento, todas las nuevas notificaciones incluirán el prefijo sha256: en la firma
5. Tu código detectará automáticamente el nuevo formato y validará usando SHA-256

Fase 3: Verificación post-migración

Después de la activación:

1. Monitorear logs: Verifica que todas las notificaciones nuevas usen SHA-256
2. Revisar métricas: Asegúrate de que no haya incremento en notificaciones rechazadas
3. Validar alertas: Confirma que tu sistema de monitoreo no reporte anomalías

Fase 4: Limpieza (Opcional)

Una vez que confirmes que SHA-256 está funcionando correctamente durante al menos 30 días, puedes:

1. Eliminar el código legacy de soporte SHA-1
2. Simplificar tu lógica de validación para usar solo SHA-256
3. Actualizar tu documentación interna

Checklist de migración

Usa esta lista para asegurar una migración exitosa:

• Código actualizado para soportar ambos algoritmos (SHA-1 y SHA-256)
• Pruebas realizadas en ambiente de desarrollo/staging
• Logging implementado para rastrear el uso de algoritmos
• Coordinación con soporte de Placetopay para activación
• SHA-256 activado en cuenta de pruebas
• Validación exitosa de notificaciones en pruebas
• SHA-256 activado en cuenta de producción
• Monitoreo activo post-migración (primeros 7 días)
• Verificación de métricas y logs (30 días)
• (Opcional) Código legacy SHA-1 removido

Preguntas frecuentes

Soporte

Si necesitas ayuda durante el proceso de migración:

• Email de soporte: [email protected]
• Documentación técnica: Notificaciones
• Documentación de autenticación: Autenticación