Webhook

Los webhooks permiten notificar automáticamente a tu sistema cuando un pago cambia de estado. Esto te permite mantener actualizada la conciliación de tus pagos sin necesidad de consultar la API de forma constante.

Desde la sección de configuración de webhooks, podrás registrar un endpoint de tu plataforma para recibir notificaciones sobre los eventos relacionados con cada pago. Estas notificaciones se envían mediante peticiones POST y pueden utilizarse para detonar procesos, actualizaciones o validaciones dentro de tu sistema.

Ambientes

Producción

https://comercios.atratopago.com/v3/partner

Sandbox

Ambiente recomendado para desarrollo y pruebas de integración.

https://sandbox-comercios.atratopago.com/v3/partner

Configuración

Con las credenciales proporcionadas para el dashboard de partners, podrás acceder a la plataforma y consultar tanto la información de solicitudes como las opciones de configuración.

Para configurar el webhook, dirígete al menú lateral izquierdo y selecciona:

Recepción de pagos → Configuración

Como se muestra en la siguiente imagen:

Datos recomendados de configuración:

URL del webhook: endpoint público HTTPS de tipo POST.
Método de autenticación: se recomienda configurar un mecanismo de validación con credenciales o datos compartidos para confirmar que la notificación proviene de Atrato.

Cuándo se envían eventos

Se envía una notificación cuando ocurre un cambio de estado del pago (status) asociado al globalPaymentId.

Estados posibles:

Estado	Cuándo ocurre
`pending_conciliation`	El pago fue registrado en sucursal, pero aún no concluye el proceso operativo
`success`	El pago quedó conciliado correctamente
`cancelled`	El pago fue cancelado

Payload del webhook

La notificación se envía por POST con Content-Type: application/json.

{
  "event": "UPDATED_STATUS_PAYMENT_CASH_IN_AT_STORE",
  "payload": {
    "paymentId": 999,
    "status": "success"
  }
}

Recomendaciones de consumo

Responde con 2xx al recibir y procesar correctamente el evento.
Valida siempre el método de autenticación configurado en tu cuenta.
Usa paymentId + status para hacer tu procesamiento idempotente.
Si recibes un evento con estado final (success o cancelled), actualiza tu orden local y evita re-procesar.
Guarda trazabilidad del payload recibido para auditoría.