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:

JSON

{  
  "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:

JSON

{  
  "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:

JSON

{  
  "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:

JSON

{  
    "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": "[[email protected]](mailto:[email protected])",  
        "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:

JSON

{  
  "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.