---
updatedAt: 2026-10-23T18:42:44.000Z
agentTools:
  projectIndex: https://docs.atratopago.com/llms.txt
---

# 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:

<Image align="center" src="https://files.readme.io/ee7934edb1d40d3710c84265bd42bdc957ce39a3f1b13905d728712f068c09ec-Captura_de_pantalla_2026-03-23_a_las_2.32.30_p.m..png" />

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**.

| Estado                 | Cuándo ocurre                                                         |
| ---------------------- | --------------------------------------------------------------------- |
| `pending_conciliation` | El pago se registró en sucursal, pero todavía no se aplica al crédito |
| `success`              | El pago se aplicó al crédito, al registrarlo o después                |
| `cancelled`            | El pago se canceló, por API o por Atrato                              |

## 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`):

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

**Pago global** (registrado con `/register-payment`):

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

<Callout icon="🚧" theme="warn">
  ### En los eventos `GLOBAL`, `paymentId` se mantiene por compatibilidad y trae el mismo valor que `globalPaymentId`. Está **deprecado**: usa `globalPaymentId`. En los eventos `CREDIT`, `paymentId` es el id del pago a crédito.
</Callout>

## 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.