Webhook de transferencia

Esta página describe el formato del webhook enviado por la plataforma cada vez que se actualiza el estado de una transferencia (retiro) vía PIX.

Descripción

El webhook de transferencia se envía automáticamente cada vez que cambia el estado del retiro, permitiendo que el sistema del integrador siga todo el ciclo de la transferencia desde la creación hasta su finalización o fallo.

Las notificaciones se envían mediante solicitudes HTTP usando el método POST y el formato JSON.

Estándar de Zona Horaria

Todos los campos de fecha y hora enviados en los webhooks utilizan el estándar ISO 8601 en la zona horaria UTC (UTC+00:00), garantizando consistencia independientemente de la zona horaria del integrador. Para evitar discrepancias causadas por horarios locales o cambios de horario de verano, se recomienda mantener los valores en UTC para almacenamiento y procesamiento, realizando la conversión a la zona horaria local solo a nivel de presentación.

Validación Opcional del Webhook

Para aumentar la seguridad, los webhooks registrados directamente en el panel pueden incluir una firma enviada en el header X-Signature: <firma-en-base64>, permitiendo validar la autenticidad de la notificación recibida. Esta firma es generada por la plataforma utilizando HMAC con SHA-256 sobre el cuerpo del webhook, en formato JSON, usando un secreto compartido WEBHOOK_SECRET y codificada en Base64. El integrador puede reproducir el mismo cálculo en su sistema usando el mismo secreto y el payload recibido. Si la firma generada coincide con la enviada en el header, el webhook se considera legítimo e íntegro. Si son diferentes, la solicitud puede haber sido alterada o no enviada por la plataforma.

Esta validación está disponible solo para webhooks registrados en el panel. Los webhooks enviados a una URL informada dinámicamente mediante notificationUrl no incluyen la firma X-Signature.

La validación por firma es opcional, pero altamente recomendada siempre que el webhook sea configurado desde el panel para garantizar mayor seguridad en la comunicación.

Endpoint de Notificación

Si se informa, el webhook será enviado a la URL configurada en el campo notificationUrl.

El endpoint debe estar disponible públicamente y responder con HTTP 200 para confirmar la recepción.

Además, las notificaciones de transferencia también pueden realizarse mediante webhooks in-bound, configurados directamente en el panel del gateway. En este modelo, el endpoint se registra previamente y se ejecuta automáticamente en cada cambio de estado de la transferencia.

Estado de la Transferencia

Los valores posibles para el campo status son:

• IN_QUEUE – Transferencia creada y en espera de procesamiento.
• IN_ANALYSIS – Transferencia en análisis.
• APPROVED – Transferencia aprobada (no pagada).
• PROCESSING – Transferencia en procesamiento.
• COMPLETED – Transferencia completada con éxito (pagada).
• REFUSED – Transferencia rechazada.
• FAILED – Fallo en el procesamiento de la transferencia.

Datos PIX

La información de la clave PIX de destino se encuentra en el objeto data:

• pixKey – Clave PIX utilizada en la transferencia.
• pixKeyType – Tipo de clave PIX (CPF, CNPJ, EMAIL, PHONE, EVP, COPYPASTE).

Formato del Payload

A continuación se muestra un ejemplo del payload enviado en el webhook de una transferencia vía PIX.

{
  "id": "pay_test_8f3k2m9xq7a1b4c6",
  "amount": 5000,
  "method": "PIX",
  "currency": "BRL",
  "status": "IN_QUEUE",
  "message": "",
  "externalRef": "order_test_1234",
  "notificationUrl": "https://example-webhook.test/notifications",
  "approvedAt": null,
  "refusedAt": null,
  "cancelledAt": null,
  "paidAt": null,
  "createdAt": "2026-01-19T17:17:34.295Z",
  "updatedAt": "2026-01-19T17:17:34.295Z",
  "data": {
    "method": "PIX",
    "pixKey": "pix_test_123e4567-e89b-12d3-a456-426614174000",
    "pixKeyType": "EVP",
    "e2e": null
  }
}