Notificaciones (Webhooks)

AutoPay utilizará este endpoint para informarte sobre cobros fallidos y cambios en el ciclo de vida del autopago.

Importante:

Las transacciones aprobadas se envían exclusivamente a través de Settlement.
Aunque este endpoint pertenece a contratos y existe una Autenticación de contratos, la integridad del mensaje debe validarse mediante la Firma Digital descrita a continuación.

Eventos disponibles

Evento	Descripción
`AUTOPAY_CREATED`	El usuario finalizó el registro y el autopago está activo.
`AUTOPAY_UPDATED`	Se actualizó el medio de pago o las reglas del autopago.
`AUTOPAY_TRANSACTION_FAILED`	Un intento de cobro automático falló (ej. fondos insuficientes).
`AUTOPAY_CANCELED`	El autopago ha sido cancelado y no generará más cobros.

Validación de seguridad (firmas)

Es crítico verificar que la notificación proviene realmente de Placetopay. Para ello, firmamos cada mensaje digitalmente. Debes replicar este proceso en tu servidor y comparar el resultado.

Ejemplo de validación:

Supongamos que tu secretKey es ABC123example456trankey+789abc012def3456ABC= y recibes el siguiente payload:

1. Payload Recibido

{
   "id": "111111-2222-3333-4444-555555555555",
   "type": "AUTOPAY_TRANSACTION_FAILED",
   "date": "2023-01-01 12:00:00",
   "signature": "sha256:a1b2c3d4e5..."
}

Proceso paso a paso

Concatenar: Une los valores de id, type, date y tu secretKey (en este orden exacto, sin espacios ni separadores).

Cadena = 111111-2222-3333-4444-555555555555 + AUTOPAY_TRANSACTION_FAILED + 2023-01-01 12:00:00 + ABC123example456trankey+789abc012def3456ABC=
Hashear: Aplica el algoritmo SHA-256 a la cadena resultante.
Comparar: Si tu hash coincide con la signature recibida (omitiendo el prefijo sha256:), la petición es auténtica.

Si la firma no coincide, responde HTTP 400 e ignora el mensaje. Nunca expongas tu secretKey en el frontend o repositorios públicos.

POST/autopay/webhook

Estructura del webhook

Recomendación: El webhook es una notificación de evento. Para garantizar que tienes la información más reciente y detallada, se recomienda consultar la API de Buscar AutoPagos usando el id recibido.

Solicitud

Name
id
Type
string
is Required
REQUIRED
Description
Identificador único del AutoPago
Ejemplo:2972c13d-6315-4da3-80d7-64c24eb232ad
Formato:uuid
Longitud máxima:36
Longitud mínima:36
Name
type
Type
string
is Required
REQUIRED
Description
Tipo de evento notificado. Ver más en Eventos Webhook.
Valores permitidos:AUTOPAY_CREATEDAUTOPAY_UPDATEDAUTOPAY_CANCELEDAUTOPAY_TRANSACTION_FAILED
Name
date
Type
string
is Required
REQUIRED
Description
Fecha y hora en la que se lanzó por primera vez el evento. En formato ISO 8601.
Ejemplo:2025-09-29T17:09:29-05:00
Formato:date-time
Name
signature
Type
string
is Required
REQUIRED
Description
Firma digital del contenido del webhook para validación. Ver más en Validación de Webhooks.
Ejemplo:sha256:a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s
Name
reference
Type
string
is Required
REQUIRED
Description
Referencia del AutoPago proporcionada por el cliente/comercio, esta referencia debe ser unica activa por comercio.
Ejemplo:ACC00012345
Longitud máxima:32
Name
additional
Type
object
is optional
CONDITIONAL
Description
Objeto que contiene información relevante para identificar el autopago e información del evento.

Solicitud

POST

{{baseURl}}/autopay/webhook

{
    "id": "2972c13d-6315-4da3-80d7-64c24eb232ad",
    "reference": "ACC00012345",
    "type": "AUTOPAY_CREATED",
    "date": "2023-01-19 15:57:23",
    "signature": "sha256:a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s"
}

Respuesta

El webhook fue recibido correctamente.

Name
status
Type
Status
is optional
Description
Estructura para definir estados de respuestas

Respuesta

    {
      "status": {
         "status": "OK",
         "reason": "00",
         "message": "Respuesta exitosa",
         "date": "2025-09-29T17:09:29-05:00"
      },
    }