Payout filter list

Un control opcional por participante que decide qué cuentas destino puedes pagar. Lo configuras una vez para tu Fin ID y Shinkansen revisa cada payout entrante contra tus listas antes de ejecutarlo.

¿Para qué sirve?

En simple: tú defines tu propia whitelist y blacklist de cuentas destino. Shinkansen te las aplica en todos los pagos que envías, con un flujo de doble control (maker-checker + 2FA) para cambiarlas.

La blocklist rechaza pagos a cuentas marcadas como fraude o compliance hold.
La allowlist solo permite pagos a cuentas pre-aprobadas (útil para payroll, proveedores recurrentes, movimientos intra-company).
Los cambios en las listas requieren aprobación de un segundo usuario y 2FA desde el dashboard — no se pueden mover solo por API.

Modos

Tu Fin ID tiene en todo momento uno de estos tres modos. El default es free (sin control).

Modo	Qué rechaza
`free`	Nada. El filtro no corre; cualquier cuenta destino es válida.
`blocklist`	Pagos a cuentas presentes en la blocklist.
`controlled`	Pagos a cuentas en la blocklist + pagos a cuentas que no estén en la allowlist.

En controlled, la blocklist se evalúa primero: una cuenta que aparece en ambas listas se rechaza como blocked (compliance hold prevalece sobre allowlist).

Flujo maker-checker

Agregar, remover o cambiar el modo pasa por una cola de approval en el dashboard, no se aplica directamente.

sequenceDiagram
    autonumber
    actor Maker as Usuario (maker)
    actor Checker as Usuario (checker)
    participant Dashboard as Dashboard Shinkansen
    participant Core as Shinkansen Core

    Maker->>Dashboard: Agrega entries (vía UI o CSV) o cambia modo
    Dashboard->>Core: POST /entries/bulk (crea request pendiente)
    Core-->>Dashboard: request pendiente creado
    Checker->>Dashboard: Revisa el request pendiente
    Checker->>Dashboard: Aprueba con 2FA (TOTP)
    Dashboard->>Core: PATCH /requests/:id/approve + X-2FA-Token
    Core-->>Dashboard: entries aplicadas, request cerrado

Dos reglas que vale la pena marcar:

El maker y el checker no pueden ser el mismo usuario. Un request creado por alice@acme.cl solo puede aprobarlo otro usuario de la organización.
2FA es obligatorio para aprobar aunque el usuario tenga enrollment TOTP opt-in para otras acciones. El token de 2FA se adjunta en el header X-2FA-Token de la aprobación.

Alertas

Cuando un payout se rechaza por el filtro, Shinkansen produce dos salidas independientes:

Dashboard: la rejection aparece en el listado Payouts → Alertas de filtro con el detalle (reason, cuenta, mode al momento del check, filter_reason).
Webhook outgoing (opcional): si registras un endpoint en la fin property payout_filter_alert_webhook_endpoint, recibes un POST firmado con JWS por cada rejection. Ver Webhook payout_filter_alert para el payload y la verificación de firma.

Roles

Esta sección agrega tres roles nuevos a tu organización. Puedes asignarlos desde Users en el dashboard:

Rol	Puede ver listas	Puede crear requests	Puede aprobar requests
`payout_filter_viewer`	✓
`payout_filter_editor`	✓	✓
`payout_filter_approver`	✓		✓

Un usuario con rol admin tiene las tres capacidades.

Entries y formato CSV Catálogo de reasons, account_types soportados y formato del CSV para carga masiva Rechazos y webhook de alertas Semántica del rechazo en el payout receive + payload del webhook payout_filter_alert

Perú

Entries y formato CSV