Skip to main content
Bank Transfer 3.0.x cobra comisiones mediante el plugin de comisiones independiente, 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.
Bank Transfer usa solo los paquetes de comisiones de plugin-fees. Si también mantienes paquetes de facturación en plugin-fees, vuelve a crearlos como paquetes de facturación de Midaz antes de retirar plugin-fees. Esta página no los mapea.
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 cada MIDAZ_FEE_MODE_REFRESH (predeterminado 5m). Cuando no puede leer la versión, mantiene el modo que ya tiene, o usa legacy si 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_ENABLED activa la integración con plugin-fees. Con false, el valor predeterminado, Bank Transfer no llama a plugin-fees, y cada transferencia corre con comisión 0.
  • Define native solo 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ó.
No dependas de auto durante la migración. Con auto, Bank Transfer 3.1.0 pasa a native por sí solo en cuanto lee Midaz 4.1.0 o posterior. Las transferencias nuevas pasan entonces a usar los paquetes de Midaz. Si tus paquetes todavía están solo en plugin-fees, Midaz no encuentra ningún paquete, y esas transferencias quedan sin comisión.En Bank Transfer 3.1.0, BTF_FEE_ENABLED no impide que Midaz cobre comisiones en el modo native. Para detener una comisión, deshabilita su paquete de Midaz con enable: false, o elimina el paquete. Midaz entonces tampoco cobra comisión a una transferencia native que todavía no ha registrado.

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_bindings indica esa ruta. Consulta Enrutamiento del ledger.
  • Tres permisos de Midaz para las credenciales de Midaz de Bank Transfer: el recurso packages con la acción get, el recurso estimates con la acción post, y el recurso organizations con la acción get. En el modo single-tenant, son las credenciales de MIDAZ_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.
El modo 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 compara transactionRoute 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.
Un paquete de Midaz cobra cada transacción /v2 de su ledger que coincide con su alcance, venga de cualquier producto, no solo las transferencias de Bank Transfer. Un paquete sin transactionRoute coincide con todas las transacciones. Un paquete con ruta coincide con todas las transacciones registradas con esa ruta. Da a cada paquete de Bank Transfer su ruta de transacción, y no uses esas rutas de transacción en otros productos.Un ledger cuyo vínculo usa mode: omit no tiene un paquete seguro: el único que puede coincidir con sus transferencias no tiene ruta, así que cobra cada transacción /v2 del ledger. Da a ese vínculo la ruta de transacción de Midaz de cada tipo de transferencia en la página Rutas contables de Console, y revisa allí Cutover readiness. Esto cambia la contabilización de cada registro de Bank Transfer en ese ledger. Hazlo después del paso 2, cuando Midaz ya ejecute la 4.1.0 o posterior, y antes del cambio.

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 transactionRoute y el segmentId de 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 sin segmentId.
  • 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 segmentId de ese paquete. Crea el paquete de Midaz sin segmentId.
  • 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. Agrega segment:<segment-uuid> al waivedAccounts de 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 segmentId nunca coincide con un TED IN. Crea cada paquete de TED IN sin segmentId. 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 responde 422 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 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.
Crea cada paquete en Midaz con el mapeo y las reglas de alcance de arriba. Define 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.
También puedes crear los paquetes en la página Fee Packages de Console.
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:
  1. Con legacy, llama a POST /v1/transfers/initiate para 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. Registra feeAmount y packageAppliedId de cada respuesta. No proceses esas iniciaciones. Una iniciación no registra nada en Midaz. Graba una fila en payment_initiations que vence en expiresAt, guarda una huella de duplicados durante 300 segundos de forma predeterminada, y envía un evento payment_initiation.created a tus consumidores de webhooks y de eventos. Una iniciación de TED OUT fuera de la ventana de operación responde 422 BTF-0010.
  2. Pasa homologación a native, como en el siguiente paso.
  3. Repite las mismas iniciaciones. Compara cada feeAmount. packageAppliedId indica 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 responde 409 BTF-0012, así que espera a que pase.
  4. 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.
Espera una diferencia solo donde Alcance del paquete dice que los motores no pueden coincidir, y solo la que elegiste allí. Corrige cada otra diferencia en los paquetes de Midaz, y repite los casos.
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 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.
  1. Da a las credenciales de Midaz de Bank Transfer los permisos packages (get), estimates (post) y organizations (get).
  2. Habilita cada paquete de Midaz que creaste en el paso 3. Envía "enable": true con Actualizar un paquete. Ninguna iniciación prueba un TED IN, así que antes compara el transactionRoute de cada paquete de TED IN con la Transaction route del vínculo TED_IN de su ledger, en la página Rutas contables de Console.
  3. Define MIDAZ_FEE_MODE=native.
  4. Reinicia cada pod de Bank Transfer.
Justo después del reinicio, ejecuta de nuevo los mismos casos, con las mismas cuentas. Compara cada 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.
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 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:
  1. Define MIDAZ_FEE_MODE=legacy.
  2. Reinicia cada pod de Bank Transfer.
Las transferencias nuevas vuelven entonces a usar plugin-fees. Esto requiere 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.

Ver también