plugin-fees. Bank Transfer 3.1.0 y posteriores pueden cobrarlas mediante el Fees Engine que corre dentro de Midaz 4.1.0 y posteriores. Esta página mueve tus paquetes de comisiones de plugin-fees a Midaz. Después, pasa Bank Transfer a Midaz en un orden que mantiene el cobro de cada transferencia.
Sigue esta página cuando se cumplan todas estas condiciones:
- Ejecutas Bank Transfer 3.0.x.
- Tus paquetes de comisiones están en plugin-fees.
- Vas a actualizar a Bank Transfer 3.1.0 o posterior y a Midaz 4.1.0 o posterior.
Lerian Console gestiona solo paquetes de comisiones de Midaz. No muestra los paquetes que están en plugin-fees. Consulta Console.
Cómo elige Bank Transfer quién cobra la comisión
Desde la 3.1.0, la variable
MIDAZ_FEE_MODE de Bank Transfer decide quién calcula y cobra la comisión de cada transferencia.
- Bank Transfer no arranca con ningún otro valor.
- Con
auto, Bank Transfer vuelve a leer la versión de Midaz cadaMIDAZ_FEE_MODE_REFRESH(predeterminado5m). Cuando no puede leer la versión, mantiene el modo que ya tiene, o usalegacysi todavía no tiene ninguno. - Bank Transfer fija el modo de una transferencia P2P o de un TED OUT en
/initiate, y el de un TED IN cuando lo recibe. Cada paso posterior de esa transferencia usa el mismo modo: reintentos, confirmación, cancelación y conciliación. Un cambio de modo vale solo para transferencias nuevas. - En el modo
legacy,BTF_FEE_ENABLEDactiva la integración con plugin-fees. Confalse, el valor predeterminado, Bank Transfer no llama a plugin-fees, y cada transferencia corre con comisión 0. - Define
nativesolo en Midaz 4.1.0 o posterior. Midaz 4.0.x cobra comisiones sin marcar los asientos de comisión, así que Bank Transfer no puede leer la comisión que cobró.
Antes de empezar
Necesitas:
- Midaz 4.1.0 o posterior, o un plan para actualizar a esa versión. Consulta Actualización de Midaz.
- Bank Transfer 3.1.0 o posterior, o un plan para actualizar a esa versión.
- Acceso a la API de plugin-fees, para leer y estimar tus paquetes.
- Acceso a la API de paquetes de comisiones de Midaz, o a la página Fee Packages de Console.
- Para cada ledger y tipo de transferencia, la ruta de transacción de Midaz con la que Bank Transfer registra. La política de tenant
routing.ledger_bindingsindica esa ruta. Consulta Enrutamiento del ledger. - Tres permisos de Midaz para las credenciales de Midaz de Bank Transfer: el recurso
packagescon la acciónget, el recursoestimatescon la acciónpost, y el recursoorganizationscon la acciónget. En el modo single-tenant, son las credenciales deMIDAZ_CLIENT_ID. En el modo multi-tenant, Bank Transfer usa las credenciales de Midaz de cada tenant, así que da los tres permisos a la aplicación de cada tenant.
legacy no usa estos permisos. En el modo native, sin packages, cada iniciación de P2P y de TED OUT responde 503 BTF-2000. Sin estimates, cada iniciación que coincide con un paquete responde 503 BTF-2000. organizations es necesario porque esta página define MIDAZ_FEE_MODE=native de forma explícita: Bank Transfer entonces hace una lectura de la lista de organizaciones de Midaz, para comprobar la API /v2, antes de usar un conjunto de credenciales por primera vez. Con auto, no hace esa lectura. Sin organizations, Bank Transfer en el modo single-tenant no arranca, y en el modo multi-tenant cada iniciación de P2P y de TED OUT de ese tenant responde 503 BTF-2000.
Los ejemplos de abajo usan estas variables de shell. Cada UUID es un ejemplo. Usa los valores de tu propio entorno.
Bank Transfer accede al ledger de Midaz en MIDAZ_TRANSACTION_URL, o en MIDAZ_BASE_URL cuando aquella no está definida. Quita un /v1 o /v2 del final de esa dirección. Quítalo también en MIDAZ_LEDGER_URL, porque los paths de abajo ya traen la versión.
Mapea un paquete de plugin-fees a un paquete de Midaz
Migra solo los paquetes que están habilitados en plugin-fees. Deja fuera los deshabilitados. Midaz rechaza un paquete cuyo rango de montos se superpone con otro paquete con la misma ruta y el mismo segmento, y también cuenta los paquetes deshabilitados (error
0199). Así que una copia deshabilitada puede bloquear un paquete que necesitas.
Las reglas de comisión mantienen los nombres de sus campos y su formato JSON. Cambian tres cosas: dónde va la organización, dónde va el ledger y qué contiene transactionRoute.
Midaz rechaza un campo que no conoce. No envíes ninguno de estos:
ledgerId, id, createdAt, updatedAt y deletedAt.
Un TED OUT cobra su comisión además del monto. En el modo native, Bank Transfer rechaza un TED OUT con 422 BTF-3002 cuando el paquete que coincide con él tiene una comisión con isDeductibleFrom: true.
Ruta de transacción
plugin-fees comparatransactionRoute con un nombre que envía Bank Transfer: ted_out, ted_in o p2p. Midaz lo compara con el routeId de la transacción, que es el ID de una ruta de transacción de Midaz. Midaz acepta solo un UUID en este campo.
Para cada paquete, usa la ruta de transacción que routing.ledger_bindings indica para el ledger y el tipo de transferencia del paquete.
Alcance del paquete
plugin-fees y Midaz seleccionan el paquete de una transferencia de formas distintas, así que una copia exacta puede cobrar una comisión distinta. Aplica estas reglas a los paquetes habilitados de cada ledger:- El ledger tiene un paquete habilitado. plugin-fees lo aplica a cada transferencia dentro de su rango de montos, sea P2P, TED OUT o TED IN. Ignora el
transactionRoutey elsegmentIdde ese paquete. En Midaz, crea una copia para cada tipo de transferencia que cobraba, cada una con la ruta de transacción de ese tipo, y sinsegmentId. - Una ruta tiene un paquete. Cuando el ledger tiene más de un paquete habilitado, plugin-fees aplica el único paquete de una ruta a cada transferencia de esa ruta, dentro de su rango de montos. Ignora el
segmentIdde ese paquete. Crea el paquete de Midaz sinsegmentId. - Una ruta tiene varios paquetes. plugin-fees elige entonces por el segmento del remitente. Un remitente con segmento recibe solo un paquete con ese segmento. Un remitente sin segmento recibe solo un paquete sin segmento. Mantén cada
segmentId. Midaz también aplica un paquete sin segmento a un remitente que tiene segmento, cuando ningún paquete de ese segmento cubre el monto. Si la ruta tiene un paquete sin segmento, decide qué comportamiento quieres. Cuando cada comisión de ese paquete se cobra además del monto (isDeductibleFrom: false), puedes mantener el comportamiento de plugin-fees. Agregasegment:<segment-uuid>alwaivedAccountsde ese paquete para cada segmento del ledger, y para cada segmento que crees después. Midaz entonces no cobra ninguna de sus comisiones a un remitente en esos segmentos. En una comisión descontada del monto, la exención también exime a un destinatario en esos segmentos, así que no la uses en ese caso. Para un paquete así, los motores no pueden coincidir. Decide si un remitente cuyo segmento no tiene paquete propio para ese monto lo paga en Midaz, o si lo dejas fuera, de modo que un remitente sin segmento no pague ninguna de sus comisiones. - TED IN. Para un TED IN, Bank Transfer enviaba a plugin-fees el segmento de la cuenta del destinatario. Midaz lee el segmento de las cuentas de origen, y omite la cuenta externa, que es el único origen de un TED IN. Así que un paquete de Midaz con
segmentIdnunca coincide con un TED IN. Crea cada paquete de TED IN sinsegmentId. Si el ledger tiene más de un paquete de TED IN en plugin-fees, plugin-fees cobraba a un destinatario con segmento solo un paquete con ese segmento, y a un destinatario sin segmento solo un paquete sin segmento. Midaz no ve el segmento del destinatario, y aplica los paquetes sin segmento a cada destinatario. Decide el precio de TED IN que vale para cada destinatario. - Un paquete sin ruta. Cuando el ledger tiene más de un paquete habilitado, plugin-fees nunca aplicaba un paquete sin ruta a una transferencia de Bank Transfer, porque Bank Transfer siempre envía una ruta. Déjalo fuera.
- Dos paquetes que coinciden. Midaz selecciona el paquete que cumple el mayor número de restricciones. Cuando dos paquetes coinciden por igual, Midaz rechaza la transacción con el error
0198. En la iniciación, Bank Transfer responde422 BTF-2005.
Migra paso a paso
1
Fija el modo legacy
Define
MIDAZ_FEE_MODE=legacy en el entorno de Bank Transfer. En el Helm chart, la clave es bankTransfer.configmap.MIDAZ_FEE_MODE, y el chart usa auto cuando la clave no está definida. Bank Transfer 3.0.x ignora la variable, así que puedes definirla antes de la actualización.Comprueba el valor que genera tu despliegue antes de actualizar, por ejemplo con helm template o helm diff. Una actualización gradual no se detiene después del primer pod, a menos que la pauses.Mantén BTF_FEE_ENABLED=true y las variables FEES_* como están.2
Actualiza Bank Transfer y después Midaz
Actualiza Bank Transfer a 3.1.0 o posterior. Espera a que cada pod de Bank Transfer ejecute la 3.1.0 o posterior. Una versión anterior no puede liquidar una transferencia que Bank Transfer creó en el modo
native.Busca en el log de cada pod la línea midaz: fee mode resolved con feeMode=legacy y source=config. En el modo single-tenant, un pod la registra al arrancar. En el modo multi-tenant, la registra para cada tenant en la primera transferencia de ese tenant. source=config prueba que la fijación funciona. Compruébalo mientras Midaz todavía ejecuta una versión anterior a la 4.1.0. En ella, auto también resuelve a legacy, así que una transferencia que paga la comisión de plugin-fees no prueba la fijación.Actualiza Midaz a 4.1.0 o posterior.Haz una transferencia pequeña. Comprueba que plugin-fees todavía cobra su comisión.3
Vuelve a crear cada paquete habilitado en Midaz
Lista los paquetes habilitados de cada ledger en plugin-fees. Cada respuesta trae una página, y su Crea cada paquete en Midaz con el mapeo y las reglas de alcance de arriba. Define También puedes crear los paquetes en la página Fee Packages de Console.
total cuenta solo los elementos de esa página. Lee la página siguiente hasta que una página traiga menos elementos que limit. La lista deja fuera los paquetes eliminados.enable como false. Guarda la lista de los paquetes que creas: habilitas exactamente esos en el cambio. Este ejemplo vuelve a crear una comisión fija de TED OUT. Su transactionRoute es la ruta de transacción de TED OUT del vínculo del ledger.4
Compara las comisiones de los dos motores
Para cada paquete, estima la misma transacción en plugin-fees y en Midaz. Compara los montos de las comisiones. Deben ser iguales. Usa montos en los dos extremos del rango del paquete, y un monto en el medio. Para un paquete que tiene las exenciones de segmento de Alcance del paquete, usa un remitente fuera de esos segmentos. Midaz exime a un remitente en ellos por diseño, y plugin-fees no.En la respuesta de Midaz, cada asiento de comisión tiene
"feeLeg": "true" en su metadata. También puedes usar el Fee Calculator de Console.Una estimación calcula el único paquete que indicas. No comprueba transactionRoute ni segmentId, así que no muestra qué paquete recibe una transferencia. El siguiente paso lo prueba.5
Ensaya la selección en homologación
Ejecuta primero los pasos 1 a 4 en homologación, con los mismos paquetes. Después prueba qué paquete recibe cada transferencia, antes de hacer el cambio en producción:
- Con
legacy, llama aPOST /v1/transfers/initiatepara cada caso: P2P y TED OUT, desde un remitente en cada segmento del ledger y desde un remitente sin segmento, con montos en los dos extremos del rango de cada paquete. RegistrafeeAmountypackageAppliedIdde cada respuesta. No proceses esas iniciaciones. Una iniciación no registra nada en Midaz. Graba una fila enpayment_initiationsque vence enexpiresAt, guarda una huella de duplicados durante 300 segundos de forma predeterminada, y envía un eventopayment_initiation.createda tus consumidores de webhooks y de eventos. Una iniciación de TED OUT fuera de la ventana de operación responde422 BTF-0010. - Pasa homologación a
native, como en el siguiente paso. - Repite las mismas iniciaciones. Compara cada
feeAmount.packageAppliedIdindica ahora el paquete de Midaz. Comprueba que es el paquete que sustituye al de plugin-fees. Una iniciación idéntica dentro de esa ventana de duplicados responde409 BTF-0012, así que espera a que pase. - TED IN no tiene iniciación. En cada modo, recibe un TED IN pequeño para un destinatario en cada segmento y para un destinatario sin segmento. Compara las comisiones.
6
Pasa Bank Transfer a native
Antes del cambio, ejecuta en producción los casos de iniciación de P2P y TED OUT del paso 5, con Las transferencias nuevas usan ahora las comisiones de Midaz. Una transferencia P2P o un TED OUT iniciados antes del reinicio, y un TED IN recibido antes de él, mantienen el modo
legacy. Usa cuentas de prueba propias, una en cada segmento y una sin segmento. Registra cada feeAmount. El paso 5 indica qué graba una iniciación.- Da a las credenciales de Midaz de Bank Transfer los permisos
packages(get),estimates(post) yorganizations(get). - Habilita cada paquete de Midaz que creaste en el paso 3. Envía
"enable": truecon Actualizar un paquete. Ninguna iniciación prueba un TED IN, así que antes compara eltransactionRoutede cada paquete de TED IN con la Transaction route del vínculoTED_INde su ledger, en la página Rutas contables de Console. - Define
MIDAZ_FEE_MODE=native. - Reinicia cada pod de Bank Transfer.
feeAmount, y revisa cada packageAppliedId. Espera una diferencia solo donde Alcance del paquete dice que los motores no pueden coincidir, y solo la que elegiste allí. Una iniciación idéntica dentro de la ventana de duplicados responde 409 BTF-0012, así que espera a que pase la ventana entre las dos rondas. Una iniciación no registra nada en Midaz, así que estos casos muestran una ruta o un ID de segmento erróneo sin mover dinero.Si aparece otra diferencia, revierte la migración. Corrige las comisiones o el rango de montos de un paquete con Actualizar un paquete. Actualizar un paquete no cambia transactionRoute ni segmentId, así que, para una ruta o un segmento erróneo, crea un paquete corregido con enable: false, y elimina el erróneo solo después de que terminen las transferencias native que lo usaron. Esta consulta lista las transferencias creadas en el modo native desde el inicio del reinicio. Revisa a mano la comisión de cada una.legacy hasta que terminan.7
Comprueba transferencias reales
Haz una transferencia P2P o un TED OUT pequeños. Comprueba la comisión que Bank Transfer muestra en la iniciación. Comprueba la comisión que registra en la transferencia. Las dos deben coincidir con la comisión que cobraba plugin-fees antes, salvo por una diferencia que elegiste en Alcance del paquete.Comprueba de la misma forma el primer TED IN que llegue después del cambio.En Midaz, los metadatos de cada transacción tienen
packageAppliedID. Es el ID del paquete de Midaz que cobró la comisión.8
Retira plugin-fees
Mantén plugin-fees en ejecución mientras esta consulta devuelva filas. En el modo multi-tenant, ejecútala en la base de datos de Bank Transfer de cada tenant.Son los TED IN recibidos antes del cambio. Cuando Bank Transfer retoma uno, pide su comisión a plugin-fees. Si plugin-fees está detenido, Bank Transfer acredita al destinatario sin comisión. Cuando
fees.fail_closed_default es true, devuelve la TED al remitente, a menos que Bank Transfer no pueda leer esa política.Después, haz una copia de seguridad de la base de datos MongoDB de plugin-fees y detén plugin-fees. A partir de ese momento, no puedes revertir la migración.Mantén MIDAZ_FEE_MODE=native. Con auto, un pod que no puede leer la versión de Midaz arranca en el modo legacy, y legacy necesita plugin-fees.Revertir la migración
Puedes volver a plugin-fees mientras plugin-fees siga en ejecución con sus paquetes sin cambios:
- Define
MIDAZ_FEE_MODE=legacy. - Reinicia cada pod de Bank Transfer.
BTF_FEE_ENABLED=true y las variables FEES_* todavía en su lugar.
Las transferencias creadas en el modo native mantienen ese modo. Bank Transfer las termina en la API /v2 de Midaz, y Midaz cobra sus comisiones cuando las registra. Mantén habilitados los paquetes de Midaz hasta que termine cada transferencia native.
Mantén Bank Transfer en la 3.1.0 o posterior mientras alguna transferencia creada en el modo native siga abierta. Una versión anterior liquida esa transferencia en /v1, así que su comisión no se cobra o no se registra.
Console
Las páginas de Fees Engine en Console, Fee Packages y Fee Calculator, trabajan solo con paquetes de comisiones de Midaz. No leen plugin-fees.

