Políticas de fees

Una política de fees es la regla de precio detrás de un fee: dice cuánto cobrar por un tipo de fee y a quién le aplica ese precio. Mantienes un precio general para todas las cuentas de tus usuarios o clientes y lo sobrescribes donde lo necesites — un programa con su propio plan, un cliente empresarial con términos negociados, una sola cuenta que quieres exonerar. Cuando se cobra un fee, Mono elige la política más específica que cubre la cuenta y la aplica.

Las políticas evitan tener que pedirle a Mono cada cambio de precios. Las creas, ajustas, omites (pausas) y eliminas a través del API, y siempre puedes consultar con qué política termina una cuenta — y por qué.

Antes de empezar

Vas a necesitar:

• Una API key de Core con el scope fees (fees:readonly basta para leer políticas y fees).
• Tener habilitadas las políticas de fees de Core para ti como tenant. Mono las habilita y crea tus políticas base — una por cada tipo de fee en uso — durante el onboarding.
• Conocer tus programas, propietarios de cuenta y cuentas por sus identificadores (pro_, acch_, lacc_): son a quienes puede apuntar una política (su target).

Anatomía de una política

A quién aplica una política

Una política apunta a uno de cuatro niveles (su target). De menos a más específico:

1. tenant — la política base o global. Cubre todas las cuentas de tus usuarios o clientes y es el precio de último recurso.
2. program — todas las cuentas de un programa.
3. account_holder — todas las cuentas de un mismo propietario de cuenta: uno de tus usuarios o clientes.
4. account — una sola subcuenta.

Cuando se cobra un fee en una cuenta, Mono mira las políticas de ese tipo de fee que cubren la cuenta — la suya, la de su propietario, la de su programa y la base o global (tenant) — y aplica la más específica que no esté omitida o pausada:

tenant                     la política base o global — siempre existe, precio por defecto
└── program                la sobrescribe para todas las cuentas del programa
    └── account_holder     sobrescribe ambas para todas las cuentas del propietario
        └── account        sobrescribe todo, solo para esta cuenta

Tres reglas completan el cuadro:

• Solo una política activa por tipo de fee y a quién apunta (target). Para cambiar el precio de un programa, un propietario o una cuenta que ya tiene política, actualízala; crear una segunda se rechaza.
• La política base siempre existe. Mono crea tus políticas base o globales (tenant). Puedes actualizarlas, pero no crearlas, omitirlas (pausarlas) ni borrarlas — garantizan que todo fee tenga precio.
• Una política solo cubre las monedas que incluye. Si la moneda de una cuenta no está entre las strategies de la política, esa política no le aplica y aplica la siguiente menos específica.

Qué monedas debe cubrir una política

Las monedas de strategies deben mantenerse dentro de las que soporta aquello a lo que apunta la política (su target):

Una política de program o account_holder puede entonces ponerle precio a una sola moneda y dejarle las demás a la política base — útil cuando un plan difiere en COP pero no en USD.

Ver qué política aplica

GET /v1/ledger/accounts/{account_id}/fees/policies lista, para una subcuenta, todas las políticas que la cubren, agrupadas por tipo de fee y ordenadas de la más a la menos específica, con applied: true en la que gana. Las políticas omitidas o pausadas aparecen con applied: false, así puedes ver por qué una política no está teniendo efecto. Úsalo después de crear u omitir una política para confirmar el resultado.

Cómo se calcula el precio

Cada moneda en strategies tiene su propia estrategia (strategy): una lista ordenada de reglas (rules) y un cálculo por defecto (default_calculation). Mono evalúa las reglas en orden y usa el cálculo de la primera cuyas condiciones se cumplan todas; si ninguna aplica, usa el cálculo por defecto. Una estrategia sin reglas siempre usa el cálculo por defecto, que es la forma más simple de definir un precio plano.

Cálculo

Un cálculo es un monto fijo más un porcentaje del monto de la operación:

Ambas partes son siempre explícitas — envía 0 y "0" en las que no cobras — para que ningún fee quede en cero por omisión.

Por ejemplo, en una dispersión de 2.000.000,00 COP, un cálculo con fixed: 90000, percentage: "0.004", percentage_mode: "capped" y percentage_limit: 500000 cobra 900,00 fijos más 8.000,00 variables (0.4%); con una dispersión mayor, la parte variable dejaría de crecer en 5.000,00.

Reglas y condiciones

Una regla aplica su cálculo cuando todas sus condiciones se cumplen. Las condiciones comparan una propiedad de la operación — su método, su monto, su moneda, un campo de metadata de la cuenta — contra un valor u otra propiedad. Así le pones un precio distinto a un riel de dispersión, das un descuento por encima de un monto o exoneras a las cuentas marcadas de cierta forma. La lista completa de operadores y de las propiedades que puede mirar cada tipo de fee está en Condiciones.

Tipos de fee y su procesamiento

Cada tipo de fee permite valores específicos de processing_type y processing_subtype para los fees que cobras:

Administrar políticas

Algunas cosas a saber de cada operación:

• Crear. Envía las políticas bajo policies, siempre una lista (hasta 50). El lote es atómico: si una política se rechaza, no se crea ninguna, y el path del error apunta al ítem y campo que falló — /policies/1/strategies/COP se lee "la strategy en COP de la segunda política". Una política nueva nunca nace omitida (pausada).
• Actualizar. Solo cambian los campos que envías. strategies se reemplaza completo, así que envía todas las monedas que la política debe conservar; quitar una moneda es enviar el mapa sin ella. fee_type, target_type y target_id son inmutables — para mover una política, elimínala y crea una nueva. Los cambios aplican a los fees cobrados de ahí en adelante; los ya cobrados conservan su precio.
• Omitir o pausar. skip: true omite (pausa) una política: la siguiente menos específica toma el relevo hasta que vuelvas skip a false. Las políticas base no se pueden omitir.
• Eliminar. La política deja de aplicar y desaparece de los listados, y aquello a lo que apuntaba (su target) y su tipo de fee quedan libres para una política nueva. Las políticas base no se pueden eliminar. Los fees ya cobrados siguen referenciando la política eliminada.

Ejemplo: un precio especial para un programa

Un programa de usuarios premium paga un fee de dispersión más bajo, y nada por las dispersiones ACH:

{
  "policies": [
    {
      "fee_type": "bank_transfer",
      "summary": "Programa premium — fee de transferencia bancaria",
      "transaction_description": "Fee de transferencia",
      "target_type": "program",
      "target_id": "pro_3rbnHF9AtEBSyyfqZAmnii",
      "processing_type": "inline",
      "processing_subtype": "add_posting",
      "strategies": {
        "COP": {
          "rules": [
            {
              "summary": "Las dispersiones ACH son gratis",
              "conditions": [
                {
                  "operator": "equal",
                  "left": { "property": "method" },
                  "right": { "value": "co_ach" }
                }
              ],
              "calculation": { "fixed": 0, "percentage": "0" }
            }
          ],
          "default_calculation": { "fixed": 300000, "percentage": "0" }
        }
      }
    }
  ]
}

De ahí en adelante, cada dispersión en COP desde una cuenta de ese programa cuesta 3.000,00 — salvo las ACH, que no cuestan nada — mientras las cuentas de tus otros programas conservan el precio de tu política base.

Errores

Los errores de negocio traen un error_code y, cuando se refieren a un ítem de un lote, un path que lo ubica:

Siguientes pasos

• Condiciones — todos los operadores y propiedades disponibles para tus reglas.
• Fees — qué pasa una vez una política le puso precio a un fee.
• Referencia de API de fees — los payloads completos de request y response.