Webhook

Los webhooks permiten recibir notificaciones en una URL del comercio cuando se actualiza un pago, se activa una suscripción o se procesa un cargo.

La URL de destino se configura de dos maneras:

Operación	Configuración
Pago creado por API	callback_url en la solicitud de pago.
Suscripción creada por API	callback_url en la solicitud de suscripción.
Suscripción creada en POS	Webhook del servicio PAT configurado en el Portal Comercio.
Cargos PAT y cambios de tarjeta	Webhook del evento correspondiente configurado en el Portal Comercio

1. Pagos creados por API

En en servicio Crear un Objeto Payment, indicar callback_url y return_url, ambas codificadas en Base64.

• callback_url: URL del servidor del comercio que recibirá el webhook.
• return_url: URL a la que se devuelve al usuario al finalizar el proceso.

Cuerpo del webhook:

{
  "uuid": "identificador-del-pago"
}

uuid identifica el pago. La notificación no contiene el resultado: para obtenerlo, consultar el servicio de Recuperar un Objeto Payment.

2. Suscripciones creadas por API

En el servicio Crear una Suscripcion, indicar callback_url y return_url, ambas codificadas en Base64.

El webhook notifica el resultado del proceso de inscripción, tanto cuando la suscripción queda activa como cuando falla.

Cuerpo del webhook:

{
  "uuid": "identificador-de-la-suscripcion"
}

Para conocer el estado y los datos de la suscripción, consultar el servicio Recuperar una Suscripcion.

Para este proceso, las suscripciones creadas por API utilizan su propio callback_url. La configuración del Portal Comercio se utiliza para otros eventos, como cargos y cambios de tarjeta.

3. Configuración en el Portal Comercio

En la sección Webhooks de la configuración de cuenta:

1. Seleccionar Agregar webhook.
2. Elegir el servicio PAT.
3. Seleccionar el evento.
4. Ingresar la URL del servidor que recibirá las notificaciones y guardar.

La URL se ingresa directamente, sin codificar en Base64. Se puede utilizar la misma URL para varios eventos o asignar una URL distinta a cada uno.

Los eventos PAT utilizados por los flujos revisados son:

Evento	Descripción
suscription_activated	Activación de una suscripción.
suscription_failed	Inscripción fallida.
charge_paid	Cargo pagado.
charge_reject	Cargo rechazado.
card_change	Cambio exitoso de tarjeta.

Los nombres conservan la escritura utilizada por la integración, incluyendo suscription.

4. Suscripciones creadas en POS

La activación de una suscripción en POS se notifica a la URL configurada para el servicio PAT y el evento suscription_activated.

Cuerpo del webhook:

{
  "status": "OK",
  "code": 200,
  "suscription": {
    "uuid": "identificador-de-la-suscripcion"
  }
}

status y code pertenecen a la notificación. Para conocer el estado de negocio de la suscripción, consultar la API usando suscription.uuid.

5. Cargos de suscripciones PAT

Los eventos charge_paid y charge_reject se envían a las URL configuradas en el Portal Comercio.

Ejemplo del cuerpo con detalle de un cargo pagado:

{
    "suscription_uuid": "identificador-de-la-suscripcion",
    "id": "identificador-del-cargo",
    "charge_date": "2026-10-09",
    "amount": 15000,
    "status": "pagado",
    "description": "Cuota mensual",
    "created_at": "2026-10-01 10:00:00",
    "payment": {
      "client": {
        "email": "[cliente@example.com](mailto:cliente@example.com)",
        "first_name": "Ana",
        "last_name": "Pérez",
        "social_id": "",
        "phone": ""
      },
      "commerce": {
        "commerce_id": "rut-del-comercio",
        "name": "Comercio de ejemplo"
      },
      "order": {
        "uuid": "identificador-del-pago",
        "status": "pagado",
        "created_at": "2026-10-09 09:00:00",
        "card_number": "1234",
        "authorized_at": "2026-10-09 09:00:02",
        "auth_code": "123456",
        "installment_amount": 15000,
        "installment_number": 1,
        "payment_type_code": "VN",
        "amount": 15000,
        "deposits": \[]
      }
    }
  }

• id: identificador del cargo, utilizado para consultar su detalle.
• suscription_uuid: suscripción a la que pertenece.
• status: estado del cargo, por ejemplo pagado o rechazado.
• payment: información del pago asociado. Puede ser null o no estar presente cuando no hay información disponible.
• deposits: detalle de abonos. Puede ser una lista vacía o null, según el flujo y el estado del pago.

6. Cambio de tarjeta

El evento card_change notifica que una suscripción cambió su tarjeta correctamente.

Cuerpo del webhook:

{
  "uuid": "identificador-de-la-suscripcion"
}

Consultar la suscripción mediante la API para recuperar la información actualizada.

7. Recepción de las notificaciones

El servidor del comercio debe aceptar solicitudes HTTP POST, registrar la notificación y responder rápidamente con HTTP 200.

Los ejemplos muestran el cuerpo de la notificación. Los flujos revisados envían JSON; algunos envíos PAT declaran Content-Type: application/x-www-form-urlencoded, por lo que conviene contemplar esa variante al implementar el receptor.

Se recomienda:

• Utilizar una URL pública con HTTPS.
• Procesar la operación consultando su identificador en la API.
• Contemplar notificaciones repetidas para evitar ejecutar dos veces la misma acción.
• Usar rutas distintas cuando sea necesario diferenciar eventos: varios cuerpos contienen solo uuid y no incluyen el nombre del evento.