Saltar al contenido principal
El plugin Bank Transfer divide la configuración en dos niveles. Puedes cambiar la mayoría de los ajustes de negocio en tiempo de ejecución, sin reiniciar el servicio. La identidad del tenant y el ámbito de la organización de Midaz sirven para propósitos distintos. Mantenlos separados. En Lerian Cloud, el claim tenantId del JWT en el contexto de la solicitud autenticada identifica tu tenant, y Lerian aísla tus datos. El encabezado X-Organization-Id define el ámbito de la organización de Midaz dentro de ese tenant. Cada ruta de transferencia con ámbito de organización requiere este encabezado, en todos los modos de despliegue. Una solicitud devuelve 400 si omite el encabezado o envía un valor que no es un UUID válido.

​
Niveles de configuración

El plugin Bank Transfer tiene dos niveles de configuración:
  • La configuración de infraestructura (la administra DevOps) controla URLs, credenciales, ajustes de autenticación y timeouts. Los cambios necesitan un reinicio del servicio.
  • Los ajustes en tiempo de ejecución (administrados a través de la Admin API) controlan los límites de transferencia, las políticas de comisiones, el horario de operación y el enrutamiento del ledger. Los ajustes del namespace tenant_policy se aplican a un tenant. Los ajustes del namespace runtime_config se aplican a todo el despliegue. Los cambios se aplican sin reiniciar el servicio.

​
Decisiones de negocio que puedes configurar

A los GPM y a los equipos de producto les importan estos ajustes. Los administras a través de la Admin API en tiempo de ejecución, sin despliegue, excepto las variables de despliegue como MIDAZ_FEE_MODE, que solo cambian con un reinicio.

​
Límites de transferencia

Define topes de monto diarios y mensuales por tenant con usage_limits.enabled, usage_limits.daily_limit_cents y usage_limits.monthly_limit_cents. El plugin aplica los topes a cada cuenta del remitente, sobre el monto debitado del remitente (totalAmount), cuando procesa una transferencia TED OUT, P2P o TED entre cores. El día y el mes se reinician a las 00:00 UTC. Una transferencia que supera un tope se rechaza con 422 BTF-0011.

​
Política de comisiones

La variable de despliegue MIDAZ_FEE_MODE decide quién calcula y cobra la comisión de cada transferencia TED OUT, TED IN, P2P y TED entre cores:
  • legacy: plugin-fees calcula la comisión a partir de sus propios paquetes. BTF_FEE_ENABLED activa plugin-fees. Con false, el valor predeterminado, el plugin no llama a plugin-fees, y cada transferencia se ejecuta con comisión 0.
  • native: el Fees Engine de Midaz 4.1.0 o posterior calcula y cobra la comisión a partir de los paquetes de comisiones del ledger. BTF_FEE_ENABLED no activa ni desactiva esa comisión. Para detener una comisión, deshabilita su paquete de Midaz con enable: false, o elimina el paquete.
  • auto (predeterminado): native en Midaz 4.1.0 o posterior, y legacy en una versión anterior o cuando la primera lectura de la versión falla.
Con auto, una actualización de Midaz a la 4.1.0 o posterior pasa Bank Transfer a native por sí sola. Si tus paquetes de comisiones todavía están en plugin-fees, Midaz no encuentra ningún paquete, y las transferencias nuevas quedan sin comisión. Define MIDAZ_FEE_MODE=legacy antes de actualizar Midaz y luego sigue Migra las comisiones de Bank Transfer a Midaz.
En el modo native, una iniciación puede llevar una etiqueta de comisión opcional en feeContext: una letra minúscula, seguida de hasta 49 letras minúsculas, dígitos o guiones bajos. Un paquete de comisiones en el ledger del pagador selecciona por ella. El plugin verifica la etiqueta una vez, en la iniciación. Rechaza la iniciación con 422 BTF-0008 cuando ningún paquete de comisiones en el ledger del pagador selecciona por la etiqueta, habilitado o no, o cuando el ledger no calcula comisiones de forma nativa. Los asientos de la transferencia en el ledger llevan la etiqueta, y Get Transfer la devuelve.

​
Fail-open frente a fail-closed

En el modo legacy, la política de tenant fees.fail_closed_default (predeterminado false) decide qué hace un fallo de plugin-fees:
  • TED OUT y P2P: cuando plugin-fees no está disponible, la transferencia sigue sin comisión (fail-open). Con true, el plugin rechaza la transferencia (fail-closed). Una comisión que plugin-fees rechaza siempre rechaza la transferencia.
  • TED IN: cualquier fallo de comisión acredita los fondos con comisión 0. Con true, el plugin no acredita y devuelve la transferencia al banco de origen.

​
Recepción de TED IN

El polling de TED IN está desactivado de forma predeterminada. DevOps lo activa para el despliegue con JD_POLLING_ENABLED=true, después de que las credenciales de JD SPB estén configuradas. Cuando el plugin no encuentra al destinatario de una TED IN, la política de tenant jd_polling.auto_return_authorized (predeterminado false) decide si devuelve los fondos al banco de origen o retiene el mensaje para un operador. Consulta Recibir (TED IN).

​
Horario de operación

Cada tenant tiene una ventana de TED OUT: operating_hours.window (HH:MM-HH:MM, predeterminado 06:30-17:00) en la zona horaria de operating_hours.timezone (predeterminado America/Sao_Paulo). El plugin rechaza una TED OUT fuera de la ventana, en fines de semana y en feriados de BACEN con 422 BTF-0010. La misma ventana se aplica a la devolución de una TED IN, que también cierra como máximo a las 13:00 el 24 de diciembre y el último día hábil del año. P2P ignora la ventana.

​
Enrutamiento del ledger

La política de tenant routing.ledger_bindings es un único documento JSON que vincula cada organización de Midaz, ledger y tipo de transferencia con sus rutas contables. Un vínculo o nombra las rutas de transacción y de operación de Midaz que se deben usar, o define mode: omit para registrar sin rutas. No hay fallback de un vínculo a otro. Sin un vínculo:
  • TED OUT y P2P se rechazan con 503 BTF-9015. El error nombra el ajuste que falta en systemplaneKey y la causa en reason.
  • Una TED IN queda retenida con el motivo LEDGER_ROUTE_UNRESOLVED. El plugin la acredita en cuanto exista el vínculo.
Cada tipo de crédito al cliente (TED_IN_STR0005 a TED_IN_STR0051) necesita su propio vínculo, separado de TED_IN. La devolución de una TED IN se registra en el vínculo de TED_OUT del ledger de la TED IN. Una TED entre cores se registra en el vínculo de CROSS_CORE_OUT. Un crédito entre cores recibido del otro core se registra en CROSS_CORE_IN, y la devolución de una TED entre cores que enviaste se registra en CROSS_CORE_RETURN_IN. Antes de mover tráfico, llama a Check Ledger Routing Readiness. La respuesta lleva ready: true solo cuando cada organización, ledger y tipo de transferencia en uso tiene un vínculo, y cada ruta nombrada existe en Midaz.

​
Configuración de infraestructura

DevOps define las variables de entorno de tiempo de despliegue (URLs, credenciales, TLS, persistencia, integraciones, claves de seguridad). Estas variables requieren un reinicio del servicio. Consulta la referencia completa en Variables de entorno.

​
Configuración en tiempo de ejecución (Admin API)

Administras los ajustes en tiempo de ejecución a través de la Admin API en /system/:namespace/:key, sin reinicio. Las claves de política de tenant están en el namespace tenant_policy. Las claves de todo el despliegue están en runtime_config. Los ajustes configurables incluyen:
  • Límites de transferencia (diarios y mensuales, por tenant)
  • Comportamiento de las comisiones (fees.fail_closed_default, fees.max_fee_amount_cents, fees.refund_on_devolucao)
  • Devoluciones de TED IN cuando no se encuentra al destinatario (jd_polling.auto_return_authorized)
  • Horario de operación (operating_hours.window, operating_hours.timezone)
  • Enrutamiento del ledger (routing.ledger_bindings)
  • P2P entre dos ledgers de una organización (p2p.cross_ledger_enabled). Consulta Transferencias entre ledgers
  • Un ISPB que compartes con otro core de tu institución (onus.shared_ispb_gate_enabled). Consulta Transferencias entre cores

​
Ajustes administrados por el systemplane

El systemplane (Admin API) administra los ajustes de abajo en tiempo de ejecución, no en tiempo de despliegue. El plugin ignora estas variables de entorno: si defines una, registra el WARN systemplane-managed environment variable is set and ignored. Usa el systemplane para cambiarlas.
Cuando CORS no está configurado, el origen permitido predeterminado es el comodín *. Cualquier origen puede entonces llamar a la API, y el plugin no lo valida al arrancar. Para producción, define orígenes explícitos a través de la clave del systemplane cors.allowed_origins en lugar del comodín.