Rechazos y webhook de alertas

Cuando un payout entra y choca con tu payout_filter_mode, Shinkansen devuelve un rechazo en la respuesta HTTP y además persiste una alerta que puedes ver en el dashboard o recibir en tu propio sistema por webhook.

Semántica del rechazo en el payout receive

El filtro corre sobre todas las transacciones del PayoutMessage como una unidad. Si al menos una transacción es rechazada, la payout order completa se rechaza — no hay aceptación parcial.

Respuesta HTTP:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "errors": [
    {
      "error_code": "payout.account_blocked",
      "error_message": "Account 00987654321 at SANTANDER_CL is in your blocklist (fraud_reported)",
      "transaction_id": "e3b0c442-98fc-4c14-9b1a-aaaaaaaaaaaa"
    }
  ]
}

Códigos de error que puede devolver el filtro:

Webhook payout_filter_alert

Opcional. Si quieres recibir las rejections del filtro en tu propio sistema (para alertar a un equipo de riesgo, levantar un ticket, etc.), registra un endpoint en la fin property payout_filter_alert_webhook_endpoint.

Configuración

Desde el dashboard: Settings → Webhooks → Payout filter list → Payout filter alert endpoint.

El campo acepta una URL o una lista de URLs. Cada rejection produce un POST por URL registrada; una falla en una URL no afecta a las otras.

Payload

{
  "shinkansen_alert_id": 12345,
  "fin_id": "ACME_CL",
  "transaction_id": "e3b0c442-98fc-4c14-9b1a-aaaaaaaaaaaa",
  "account_type": "current_account",
  "creditor_fin": "SANTANDER_CL",
  "account": "00987654321",
  "reason": "blocked",
  "filter_reason": "fraud_reported",
  "filter_reason_text": "Reportado por el usuario el 2026-10-20",
  "mode_at_check": "blocklist",
  "inserted_at": "2026-10-29T15:42:11Z"
}

Notas sobre los campos:

• shinkansen_alert_id es el id interno del registro en Shinkansen. Es tu clave de deduplicación: dos entregas con el mismo shinkansen_alert_id son el mismo evento.
• reason toma uno de blocked, not_allowlisted, filter_check_unavailable (mismo set que el error_code del rechazo HTTP, sin el prefijo payout.).
• filter_reason y filter_reason_text vienen de la entry que generó el match. En not_allowlisted y filter_check_unavailable llegan como null (no hay entry que haya hecho match).
• mode_at_check registra el modo del Fin al momento del check — blocklist, controlled o null (este último solo en el fail-closed path).

Verificación de firma

El payload va firmado JWS en el header shinkansen-jws-signature (formato detached: <protected>..<signature>), con el certificado público de Shinkansen que ya usas para los otros webhooks que te envía la plataforma. Si todavía no verificas firmas, revisa la guía de seguridad de webhooks.

Entrega y reintentos

• Shinkansen reintenta hasta 5 veces con backoff exponencial ante fallas de transporte o respuestas 5xx.
• Respuestas 2xx y 409 se tratan como entrega exitosa. Usa 409 cuando tu sistema ya tiene el shinkansen_alert_id registrado.
• Después del 5º intento fallido el delivery queda en estado discarded. La alerta sigue visible en el dashboard — el webhook no es la única fuente de verdad.

Dónde ver las alertas en el dashboard

Payouts → Alertas de filtro. El listado tiene filtros por fecha, por reason, por cuenta (búsqueda substring) y paginación. Cada fila muestra el detalle completo que llega en el webhook.