Eventos disponibles
Cada evento indica los tipos de transferencia a los que aplica (entre paréntesis), cuándo se dispara y la acción recomendada. La devolución de una TED IN o de un P2P envía solo sus propios eventos de devolución, nunca un evento
transfer.*. Los mismos eventos llegan al flujo de eventos: consulta Eventos de TED JD.
Ciclo de vida de la transferencia (TED OUT, P2P, TED entre cores)
transfer.initiated (TED OUT, TED entre cores)
- Disparador: el plugin creó el registro de la transferencia TED OUT o TED entre cores después de confirmar la iniciación.
- Acción: actualiza el estado de la transferencia en tu sistema. Muestra “transferencia en curso” al cliente.
transfer.processing_started (TED OUT)
- Disparador: la transferencia TED OUT entró en procesamiento (ruta de estados CREATED a PENDING a PROCESSING).
- Acción: muestra al cliente que la transferencia está en curso.
transfer.rejected (TED OUT, TED entre cores)
- Disparador: JD SPB rechazó la solicitud de transferencia en el envío, o el STR rechazó la liquidación. Para una TED entre cores, el otro core rechazó el crédito, o JD Courier no alcanzó a ningún destinatario.
- Acción: avisa al cliente del rechazo. El plugin ya canceló la retención de fondos.
transfer.completed (TED OUT, P2P, TED entre cores)
- Disparador: la transferencia se liquidó. Para un TED OUT, el STR la liquidó, o un operador la liquidó manualmente. Para una TED entre cores, el otro core acreditó al destinatario.
- Acción: avisa al cliente. Genera un comprobante. Actualiza la vista del saldo.
Conciliación (TED OUT, TED IN)
transfer.reconciliation_required
- Disparador: una transferencia con resultado desconocido pasó a conciliación.
- Acción: sigue la transferencia como pendiente. No supongas éxito ni fallo.
transfer.reconciliation_resolved
- Disparador: la conciliación terminó y la transferencia llegó a un resultado final.
- Acción: actualiza la transferencia a su estado final.
transfer.reconciliation_exhausted
- Disparador: la conciliación se detuvo después del número máximo de intentos.
- Acción: escala la transferencia para revisión manual de un operador.
transfer.reconciliation_failed
- Disparador: un intento de conciliación encontró un error determinista, que hizo fallar la transferencia.
- Acción: trata la transferencia como fallida e investiga.
transfer.reconciliation_manual_retry_requested
- Disparador: un operador devolvió una transferencia a la cola de conciliación para otro intento.
- Acción: registra la intervención manual y su motivo. El cambio de estado y este hecho no están acoplados de forma atómica. Si el evento no llega, confirma el estado de la transferencia con la API.
transfer.scope_repaired
- Disparador: un operador corrigió el ledger de Midaz en el que está registrada una transferencia, con Repair Transfer Ledger Scope. No se movió dinero.
- Acción: actualiza la referencia de ledger que guardas para la transferencia.
Transferencias entrantes (TED IN)
transfer_incoming.completed
- Disparador: el plugin recibió una TED entrante, encontró al destinatario y aplicó el crédito. También se dispara para un crédito o una devolución entre cores recibidos del otro core de tu institución.
- Acción: avisa al destinatario que los fondos llegaron. Actualiza la vista del saldo.
transfer_incoming.chargeback
- Disparador: el banco emisor aplicó un chargeback a una TED IN completada (STR0010R2), y el plugin retiró el monto acreditado de la cuenta del destinatario. Estado:
FAILED. - Acción: avisa al destinatario. Empieza una revisión con tu equipo de compliance si tu política lo requiere.
transfer_incoming.return_requested
- Disparador: una devolución de una TED IN entró en procesamiento. La retención está vigente, y el STR0010 está por enviarse.
- Acción: muestra al destinatario que los fondos vuelven al banco pagador.
transfer_incoming.returned
- Disparador: el STR liquidó la devolución de una TED IN.
- Acción: actualiza la vista del saldo y registra la devolución.
transfer_incoming.return_rejected
- Disparador: la devolución de una TED IN se rechazó, y el plugin canceló su retención.
- Acción: avisa a la persona que pidió la devolución.
transfer_incoming.return_manual_review
- Disparador: la devolución de una TED IN espera a un operador.
- Acción: resuélvela con Resolve Transfer Reconciliation.
transfer_incoming.undeliverable
- Disparador: el plugin no pudo acreditar una TED entrante (por ejemplo, no encontró la cuenta del destinatario).
- Acción: investiga la transferencia. El plugin la devuelve al banco de origen, o la retiene para un operador cuando no se encuentra al destinatario y las devoluciones automáticas están desactivadas. Consulta Recibir (TED IN).
Devoluciones e iniciación
transfer_outgoing.devolution_notified (TED OUT)
- Disparador: llegó una devolución (devolução) para una transferencia saliente.
feeRefundedindica si el plugin decidió devolver la comisión al remitente, yfeeRefundedAmountlleva la comisión cuando lo decidió. La transferencia de reembolso registra lo que asentó el ledger. - Acción: concilia los fondos devueltos contra la transferencia original.
transfer_internal.returned (P2P)
- Disparador: el ledger revirtió un P2P mediante una devolución de P2P.
- Acción: actualiza la vista del saldo de ambas cuentas.
transfer_internal.return_failed (P2P)
- Disparador: el ledger rechazó una devolución de P2P. No se movió nada, y el P2P puede devolverse de nuevo.
- Acción: avisa a la persona que pidió la devolución.
payment_initiation.created (TED OUT, P2P)
- Disparador: el plugin creó una iniciación de pago (el paso previo a la transferencia).
- Acción: opcional. Sigue las iniciaciones que esperan confirmación.
Configurar webhooks
Los webhooks funcionan por tenant. Registras un destino de una de dos formas. API de autoservicio (recomendado). Registra uno o más endpoints HTTPS con la API de registro de webhooks. El servidor genera un
signingSecret al crearlo y lo devuelve una sola vez. Guárdalo de forma segura. Úsalo para verificar la firma en cada evento entregado. También puedes listar, actualizar, deshabilitar y eliminar registros, rotar el secreto de firma y consultar los tipos de evento aceptados. El plugin deriva el tenant propietario del Bearer token, nunca de un header de solicitud.
- Crear un registro de webhook:
POST /v1/webhooks - Listar los registros de webhook:
GET /v1/webhooks - Obtener, actualizar y eliminar un registro
- Rotar el secreto de firma:
POST /v1/webhooks/{webhookId}/signing-secret/rotate - Listar los tipos de evento admitidos:
GET /v1/webhooks/event-types
WEBHOOK_ENABLED=true para activar la entrega saliente. La entrega también requiere RabbitMQ y el outbox de streaming (STREAMING_ENABLED=true). Los destinos vienen de los registros de arriba. No hay una única variable de entorno con un endpoint estático. Ajustas el comportamiento por entrega (timeout y máximo de reintentos) en runtime con systemplane, no con variables de entorno. Consulta Configuración de Bank Transfer.
Estructura del payload
El plugin entrega cada evento como un POST HTTPS. El cuerpo de la solicitud es el payload del evento en JSON. El tipo de evento y la firma viajan en headers HTTP, no en el cuerpo.
Los campos del cuerpo dependen del tipo de evento. Cada payload lleva
tenantId, y los eventos con ámbito de transferencia también llevan transferId. Los montos son cadenas decimales en la moneda de la cuenta, no centavos (por ejemplo, 100.00).
Este es un cuerpo de ejemplo para transfer.completed en una transferencia P2P:
transfer.completed lleva los montos, las cuentas y el midazTransactionId. Para los eventos con un payload más pequeño, o para leer el registro completo de la transferencia, obtén la transferencia desde Get Transfer con su transferId.
Los campos del payload cambian según el tipo de evento. Para leer todos los campos de una transferencia, usa el endpoint Get Transfer.
Manejar los fallos de entrega
Tu endpoint debe responder con un estado 2xx dentro de 5 segundos (el valor predeterminado de
webhook.timeout_ms). Si no lo hace, el plugin reintenta la entrega con backoff exponencial y jitter completo. Una respuesta 4xx distinta de 429 detiene los reintentos de inmediato, y el plugin no sigue redirecciones. Después del primer intento, el plugin hace hasta 3 intentos más (el valor predeterminado de webhook.max_retries), lo que da 4 intentos de entrega en total. La base del backoff es de 1 segundo y se duplica en cada intento. El jitter completo aplica a cada espera:
Después de que fallan todos los intentos (4 de forma predeterminada), el evento pasa a una cola dead-letter (DLQ). Configura alertas sobre la DLQ para detectar temprano los fallos de entrega persistentes. List DLQ Messages lee la cola, y Retry DLQ Message envía un mensaje de nuevo. Estas dos rutas solo existen cuando la autenticación está activada. Ajusta
webhook.max_retries con systemplane si tu endpoint necesita un presupuesto de reintentos más largo o más corto. El ajuste webhook.retry_backoff_ms controla el backoff de reconexión con el broker, no el calendario de reintentos HTTP por entrega de arriba.
Para una entrega confiable, sigue estas reglas:
- Responde dentro de 5 segundos.
- Usa HTTPS con un certificado válido.
- Devuelve 200 incluso para los eventos que ignoras.
- Mueve el procesamiento pesado a una cola en segundo plano. Mantén rápido el handler del webhook.
Idempotencia
Tu endpoint puede recibir el mismo evento más de una vez. Usa el
transferId del cuerpo y el header X-Webhook-Event para deduplicar. Para los eventos de devolución de una TED IN, agrega status y reconciliationReasonCode del cuerpo. Si ya procesaste esa combinación, devuelve 200 y no hagas nada más.Para desarrolladores
Para el código de validación de firma (JavaScript, Python, Go), la implementación de reintentos y la checklist completa de integración, consulta la guía para desarrolladores de Bank Transfer.