Notificación

Cuando una sesión es finalizada, una notificación HTTP (Webhook) es enviada al comercio.

Para recibir notificaciones debes configurar en tu aplicación una URL de notificación. Cada vez que una sesión finalice se hará una petición HTTP a ese endpoint con información útil sobre el estado de la sesión.

Recepción de Notificación

Para aprovechar esta notificación, en tu aplicación debes:

Identificar la sesión: Con el requestId y reference buscar el pago en tu sistema, debe coincidir con una sesión que hayas creado previamente.

Validar firma del mensaje: Puedes validar que se trate de un mensaje confiable de Placetopay generando y comparando el signature.

El signature se genera con la siguiente fórmula: SHA-1(requestId + status.status + status.date + secretKey)

Si el signature generado es igual al signature que llegó en el mensaje, entonces la notificación es auténtica.

Actualizar Información Si todo lo que necesitas es el estado final de la sesión, entonces puedes actualizar el estado en tu sistema y eso sería todo.

Además, si deseas obtener más información sobre la sesión y las transacciones relacionadas, debes consultar la sesión y obtener todos los detalles de esta.

Campos adicionales

Pago Recurrente:

Información de la sesión: En el campo internalReference puedes identificar la refencia de la transacción desde nuestra plataforma.

Información de la recurrencia del pago: El campo tries indica la cantidad de veces que se va a realizar el cobro y el campo enabled si éste cobro está habilitado o deshabilitado.

Ejemplos de respuestas

{
  "status": {
    "status": "APPROVED",
    "reason": "00",
    "message": "Transacción aprobada",
    "date": "2019-01-01T12:00:00-05:00"
  },
  "requestId": 1234,
  "reference": "TEST_123424",
  "signature": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s"
}

{
  "status": {
    "status": "APPROVED",
    "reason": "00",
    "message": "Transacción aprobada",
    "date": "2019-01-01T12:00:00-05:00"
  },
  "internalReference": 1598634446,
  "reference": "564555",
  "signature": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s",
  "recurring": {
     "tries": 2,
     "enabled": 0
  }
}

Mejora tu integración

Manejo de notifcaciones duplicadas

Aunque las notificaciones duplicadas son muy raros, pueden ocurrir ocasionalmente. Como comercio, es importante manejar estos eventos adecuadamente para asegurar la integridad de tu procesamiento de transacciones. Aquí hay algunas pautas:

• Verificar el estado de la sesión: Compara el estado actual de la sesión con el estado de la notificación. Si los estados coinciden, es posible que ya tengas la versión actualizada de la sesión.
• Almacenar notificaciones procesadas: Para integraciones más avanzadas, almacena las notificaciones que han sido procesadas y compara cualquier nueva notificación por su firma para asegurarte de que no haya sido manejada previamente.

Reintentos de notificación

Es importante tener en cuenta que el webhook de notificación no se reintenta. La notificación se ejecuta solo una vez, independientemente de si no hay respuesta, la respuesta es un error, o el tiempo de conexión o respuesta se agota. Solo se realiza una llamada por cada notificación. Como integrador, asegúrate de que tu sistema esté preparado para manejar la notificación en el primer intento.

Respuestas de notificación

La respuesta para el webhook debe ser un estado HTTP 2xx de éxito. La respuesta debe darse lo antes posible. Si la lógica de negocio es demasiado compleja o lenta, te recomendamos manejar la notificación en un trabajo asíncrono. Esto asegura que la llamada del webhook sea reconocida rápidamente y el procesamiento detallado se pueda hacer en segundo plano sin retrasar la respuesta.

Recepción de notificaciones en un servidor HTTPS

La URL de notificación debe ser segura y debe usar HTTPS en internet. Asegúrate de que tu servidor soporte TLS 1.2 o 1.3 para mantener un alto nivel de seguridad en las notificaciones.

Verificación de la Firma

La firma del mensaje se envía en la propiedad signature y debe ser verificada para asegurar la integridad y autenticidad de la notificación. Usa la siguiente fórmula para verificar la firma: SHA-1(requestId + status.status + status.date + secretKey). Asegúrate de reemplazar secretKey con tu clave secreta real. Este paso de verificación es crucial para asegurar que la notificación no haya sido manipulada.