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 cambia el estado (status) de un pago, sea pago a crédito o pago global.

Payload del webhook

La notificación se envía por POST con Content-Type: application/json. El campo type indica a qué tipo de pago se refiere.

Pago a crédito (registrado con /credit-payment):

{
  "event": "UPDATED_STATUS_PAYMENT_CASH_IN_AT_STORE",
  "payload": {
    "type": "CREDIT",
    "paymentId": 615,
    "status": "success"
  }
}

Pago global (registrado con /register-payment):

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

Recomendaciones de consumo

• Responde con 2xx al recibir el evento. Si tu endpoint no responde 2xx, Atrato reintenta hasta 3 veces.
• Valida siempre el método de autenticación configurado en tu cuenta.
• Usa type + id + status para hacer tu procesamiento idempotente: el mismo evento puede llegar más de una vez.
• No dependas del orden de llegada. Si recibes cancelled, ese es el estado final aunque después llegue otro evento; ante la duda, consulta el detalle del pago.
• Guarda trazabilidad del payload recibido para auditoría.