Saltar al contenido principal
Un plan de tarifas es un conjunto de comisiones que asignas a una cuenta. Cada comisión tiene una cuota gratuita: un número de unidades en cada mes calendario que no cuestan nada. Un plan de tarifas tiene dos tipos de comisión:
  • Las comisiones de transacción se aplican a las transacciones /v2 que envía la cuenta.
  • Las comisiones de servicio se aplican cuando cobras un servicio a la cuenta, por ejemplo un extracto en papel. Las cobras con un cobro de comisiones.
Creas planes de tarifas y los asignas mediante la API. Cada cuenta tiene como máximo un plan de tarifas activo.

​
Planes de tarifas y paquetes de comisiones

Un plan de tarifas y un paquete de comisiones son entidades diferentes.
  • Una cuenta con un plan de tarifas activo paga las comisiones de su plan en las transacciones /v2 que envía. En esas transacciones, un paquete de comisiones nunca cobra a esa cuenta, también cuando ninguna comisión del plan coincide. Entonces la cuenta no paga comisión.
  • Un paquete de comisiones no cobra los asientos de comisión que agrega un plan de tarifas.

​
Crea un plan de tarifas

Crea un plan con Crear un plan de tarifas. El plan tiene estos campos:
  • label: el nombre del plan. Dos planes de un ledger que no se eliminaron no pueden tener el mismo label (0543).
  • description: opcional.
  • enable: true permite asignar el plan a cuentas.
  • timezone: la zona horaria IANA en la que el plan cuenta sus meses. El valor predeterminado es America/Sao_Paulo.
  • fees: al menos una comisión, por clave de comisión. Una clave de comisión empieza con una letra minúscula, seguida solo de letras y dígitos ASCII (^[a-z][a-zA-Z0-9]*$).
Cada comisión tiene estos campos:
  • feeLabel: el nombre de la comisión.
  • trigger: lo que hace que la comisión se aplique. Consulta Disparadores.
  • calculationModel: flatFee, percentual o maxBetweenTypes, como en un paquete de comisiones. Una comisión de servicio acepta solo flatFee (0555).
  • creditAccount: el alias de la cuenta del ledger que recibe la comisión. Midaz verifica que la cuenta exista cuando creas o actualizas el plan.
  • accounting: el transactionRoute, el operationRouteFrom y el operationRouteTo de la comisión. Consulta Rutas contables.
  • freeQuota: el número de unidades gratuitas por mes. El valor predeterminado es 0.
  • period: solo monthly, el valor predeterminado.
  • referenceAmount: solo originalAmount, el valor predeterminado.

​
Disparadores

Un disparador con type: transaction acepta estos campos:
  • direction: obligatorio. El único valor es sent: la comisión se aplica a la cuenta que envía la transacción.
  • schemes: los esquemas de transacción con los que coincide la comisión, por ejemplo TED o PIX.
  • metadata: pares opcionales que los metadatos de la transacción deben llevar todos. Un par coincide solo con un valor de metadato de tipo string igual a él.
Un disparador con type: service acepta solo serviceCode, por ejemplo PAPER_STATEMENT. Midaz almacena los esquemas y los códigos de servicio sin espacios en los extremos y en mayúsculas. Cada uno tiene de 1 a 50 letras, dígitos, guiones bajos o guiones. Un código no puede ser el esquema de una comisión y el código de servicio de otra comisión del plan (0558).

​
Rutas contables

Las reglas dependen de si el ledger valida las rutas contables (accounting.validateRoutes en la configuración del ledger): Dos comisiones de transacción de un plan con los mismos metadata no pueden seleccionar las mismas transacciones (0544). En un ledger sin validación de rutas, no pueden compartir un esquema. En un ledger con validación de rutas, no pueden compartir una ruta de transacción y un esquema, y una comisión sin esquemas ocupa cada esquema de su ruta. Dos comisiones de servicio no pueden compartir un código de servicio (0544). Si activas la validación de rutas después de crear un plan, da antes a cada comisión una ruta de transacción y las dos rutas de operación. Una comisión sin ruta de transacción rechaza con 0547 cada transacción con la que coincidiría, y cada cobro de comisiones que la nombra.

​
Versiones

Las comisiones de un plan viven en versiones. Una versión nunca cambia.
  • La creación genera la versión 1, vigente desde el instante de la creación.
  • Una actualización que envía fees genera una nueva versión con el conjunto completo de comisiones resultante.
  • effectiveFrom define el instante desde el que se aplica la nueva versión, en RFC 3339. El valor predeterminado es el instante de la solicitud. No puede ser anterior al effectiveFrom de la versión más reciente (0553). Envíalo solo con fees.
  • label, description, enable y timezone cambian el plan, no una versión.
En los fees de una actualización:
  • Una entrada con la clave de una comisión almacenada cambia los campos que envía y conserva los demás. trigger, calculationModel y accounting cambian completos.
  • Una entrada vacía ({}) elimina esa comisión.
  • Una entrada con una clave nueva agrega una comisión, con cada campo obligatorio.
  • La nueva versión parte de las comisiones de la versión más reciente. Conserva al menos una comisión.
Cuando dos actualizaciones crean una versión del mismo plan al mismo tiempo, una de ellas recibe 0559 y no crea ninguna versión. Lee el plan de nuevo y envía la actualización de nuevo. Obtener un plan de tarifas devuelve la versión vigente en el instante de la solicitud. currentVersion es la versión más alta creada, que puede empezar después. Listar las versiones de un plan de tarifas devuelve cada versión.

​
Asigna un plan a una cuenta

Asignar un plan de tarifas a una cuenta envía el accountPlanId del plan.
  • El plan debe pertenecer al ledger, existir y estar habilitado (0545).
  • Si la cuenta tiene una asignación activa de otro plan, termina en el instante en que empieza la nueva asignación, en un solo paso.
  • Si la cuenta ya tiene el mismo plan, Midaz devuelve la asignación activa y no cambia nada.
  • Cuando otra asignación de la misma cuenta ocurre al mismo tiempo, Midaz puede responder 0560 y no cambiar nada. Envía la solicitud de nuevo.
Obtener la asignación de plan de tarifas de una cuenta devuelve la asignación activa, o null, y el historial de la cuenta. Listar las cuentas asignadas a un plan de tarifas devuelve las asignaciones activas de un plan. Terminar la asignación de plan de tarifas de una cuenta termina la asignación activa. Los paquetes de comisiones vuelven entonces a aplicarse a la cuenta. Una cuenta sin asignación activa responde 0554.

​
Deshabilita o elimina un plan

  • Un plan deshabilitado (enable: false) no se puede asignar. Sigue cobrando a las cuentas que ya tiene.
  • Midaz rechaza eliminar un plan asignado a una cuenta (0546). Termina antes sus asignaciones.
  • Cuando eliminas una cuenta, Midaz termina su asignación activa. El historial de la cuenta sigue legible.

​
Cómo un plan cobra una transacción

Midaz aplica los planes de tarifas a estas transacciones /v2: direct, hold, block, unblock y cada elemento de un lote. Una transacción /v1, una anotación, una reversión y una transacción que omite las comisiones con skip.fees no usan planes de tarifas. Midaz toma una decisión para cada cuenta de origen de la transacción que tiene un plan activo, excepto las cuentas @external. Toma una decisión por cuenta, también cuando la cuenta envía desde varios saldos.

​
Coincidencia

Las comisiones de la versión vigente se comparan con la transacción:
  • En un ledger sin validación de rutas, una comisión de transacción coincide cuando sus schemes contienen el scheme de la transacción. Una transacción sin scheme no coincide con ninguna comisión.
  • En un ledger con validación de rutas, una comisión de transacción coincide cuando su transactionRoute es el routeId de la transacción y sus schemes están vacíos o contienen el scheme de la transacción.
  • En los dos casos, los metadatos de la transacción deben llevar cada par de metadata de la comisión.
  • Cuando varias comisiones coinciden, se aplica la comisión con más pares de metadata. Cuando dos o más comisiones tienen ese número de pares, Midaz rechaza la transacción con 0548.

​
Resultado

La decisión tiene uno de estos resultados: Midaz calcula una comisión cobrada sobre el monto que envía la cuenta en la transacción. En un ledger con validación de rutas, los asientos de comisión usan las rutas de operación de la comisión. La respuesta de creación tiene accountPlanFees, con un elemento para cada cuenta que tiene un plan activo: accountId, accountAlias, accountPlanId, accountPlanVersion, feeKey, outcome, unit, freeQuota y amount. Solo las respuestas de creación lo devuelven. Las lecturas, los commits, las cancelaciones y las reversiones no. Las claves de metadatos de la transacción packageAppliedID, feeApplied y feeExemption describen solo paquetes de comisiones.

​
Holds, cancelaciones y reversiones

  • Un hold cuenta la unidad cuando lo creas. El commit no cuenta nada.
  • Una cancelación o una reversión devuelve la unidad solo en el mismo mes del plan. La reversión también revierte los asientos de comisión.

​
Cuota gratuita

Una unidad es una decisión con el resultado quota o charged, o un código de servicio de un cobro de comisiones con los mismos resultados.
  • Midaz cuenta unidades por cuenta, clave de comisión y mes calendario en la zona horaria del plan.
  • El conteo pertenece a la cuenta y a la clave de comisión, no al plan. Una cuenta que pasa a otro plan con la misma clave de comisión conserva su conteo del mes.
  • Una comisión de transacción cuenta cada esquema por separado. En un ledger con validación de rutas, una comisión sin esquemas tiene un conteo para todos los esquemas de su ruta. Una comisión de servicio tiene un conteo.
  • Cuando cambias una comisión, su conteo se conserva. Una comisión con una clave nueva empieza en cero.
  • El mes es el mes en que Midaz procesa la transacción, no su transactionDate.

​
Comisiones de servicio y cobros de comisiones

Cobrar comisiones de servicio a una cuenta envía serviceCodes, con 1 a 100 códigos, y description y metadata opcionales. La solicitud necesita el header X-Idempotency (0552). Cada código de la lista es una unidad. Su resultado es uno de estos:
  • quota: la unidad está dentro de la cuota gratuita de su comisión. No cuesta nada.
  • charged: la unidad superó la cuota gratuita. Cuesta el monto fijo de la comisión.
  • not_covered: el plan de la cuenta no tiene comisión de servicio para el código, o la cuenta no tiene plan activo. No cuesta nada y no cuenta unidad.
Midaz rechaza la solicitud antes de cobrar nada cuando:
  • Ningún plan de tarifas del ledger tiene una comisión de servicio para un código (0549).
  • Un código pertenece solo a comisiones de transacción (0550).
  • En un ledger con validación de rutas, las comisiones de los códigos tienen rutas de transacción diferentes (0551), o una comisión no tiene ruta de transacción (0547).
Midaz registra las unidades cobradas como una transacción de comisión en el activo de la cuenta. Debita la cuenta y acredita el creditAccount de cada comisión. En un ledger con validación de rutas, la transacción usa la ruta de transacción y las rutas de operación de las comisiones. La description y los metadata del cobro van a la transacción de comisión. Ningún paquete de comisiones, plan de tarifas ni validación de Tracer se aplica a la transacción de comisión. Cuando Midaz rechaza la transacción de comisión, por ejemplo por fondos insuficientes, rechaza el cobro con el mismo error y no cuenta unidad. Un cobro sin unidad cobrada no tiene transacción de comisión, y su feeTransactionIds queda vacío. Nada deshace ese cobro, y sus unidades siguen contadas.
  • Un reintento con la misma clave y el mismo cuerpo devuelve el cobro registrado con el header X-Idempotency-Replayed. Un cuerpo diferente con la misma clave responde 0084. Las claves son únicas por cuenta.
  • Para deshacer un cobro, revierte su transacción de comisión. Una reversión en el mismo mes devuelve cada unidad del cobro.
  • La transacción de comisión no tiene referencia a su cobro. El feeTransactionIds del cobro los vincula.
Listar los cobros de comisiones de una cuenta devuelve primero el cobro más reciente, y period (YYYY-MM) filtra la lista. Obtener un cobro de comisiones de una cuenta devuelve un cobro.

​
Uso

Obtener el uso del plan de tarifas de una cuenta devuelve las unidades de la cuenta en un mes. period (YYYY-MM, en la zona horaria del plan) selecciona el mes. El valor predeterminado es el mes actual. Un period futuro o mal formado responde 0082, y una cuenta sin plan activo responde 0554. La respuesta tiene un elemento para cada conteo de cada comisión: feeKey, trigger, period, freeQuota, used, remaining y charged. trigger es una clave del conteo: lee feeKey en lugar de interpretarla. remaining nunca es negativo. El uso lista las comisiones y las cuotas gratuitas de la versión vigente ahora, también para un mes pasado. Para la conciliación, usa el accountPlanFees de las respuestas de creación y los cobros de comisiones.

​
Estimaciones y eventos

  • Una estimación de comisiones calcula el precio del paquete de comisiones que nombras. No lee las asignaciones de planes de tarifas.
  • El evento fee_charge.applied cubre solo paquetes de comisiones. Una comisión de un plan de tarifas o un cobro de comisiones no lo emite.

​
Permisos

Las rutas usan estos recursos de permiso de Midaz:

​
Próximos pasos

Usar planes de tarifas

Crea un plan, asígnalo y cobra comisiones paso a paso.

Lista de errores de Midaz

Consulta los códigos de 0543 a 0560.