Condiciones

Una condición es una pregunta de sí o no que una regla de fee le hace a la operación que se está cobrando: ¿esta dispersión va por ACH? ¿El monto supera un umbral? ¿La cuenta está marcada como VIP? Una regla aplica su precio solo cuando todas sus condiciones responden sí. Las condiciones son la forma en que una sola política de fees le pone precios distintos a situaciones distintas, en vez de necesitar una política por caso.

Cada condición compara un operando — una propiedad de la operación, o un valor constante que tú escribes — con otro, a través de un operador. Esta página es la referencia de los operadores disponibles y de las propiedades que puede mirar cada tipo de fee.

Anatomía de una condición

{
  "operator": "greater_equal_than",
  "left": { "property": "source_amount" },
  "right": { "value": 100000000 },
  "negated": false
}

Un operando es una de dos cosas:

• Una propiedad: { "property": "method" } — el valor se lee de la operación en el momento de cobrar el fee. Algunas propiedades reciben argumentos: { "property": "account.metadata", "args": { "name": "plan" } }.
• Una constante: { "value": "co_ach" } — un string, un entero, un booleano, o una lista de ellos. Los decimales viajan como string ("0.5").

Al menos un lado de la condición debe ser una propiedad — comparar dos constantes daría siempre la misma respuesta.

Operadores

Dos detalles a tener en cuenta:

• Cuando una propiedad involucrada en una comparación numérica está vacía (null), la condición es falsa. Usa is_null si necesitas reaccionar a la ausencia de un valor.
• Los operandos deben ser compatibles: comparar un monto con un texto, o un string con una lista de números, se rechaza al crear la política (fee_policy_invalid_strategy), no se ignora en silencio después.

Propiedades

Qué propiedades puede usar una regla depende del tipo de fee: cada uno se origina en un tipo de operación — su entidad principal — y puede mirar también las entidades relacionadas con ella. Una propiedad de la entidad principal se referencia por su nombre (method); una de una entidad relacionada, como entidad.propiedad (account.name, account_holder.type).

Los montos van en la unidad mínima de su moneda (1234 son 12,34), los códigos de moneda siguen ISO 4217 (COP, USD) y los de país ISO 3166-1 alpha-2 (CO).

Dispersiones — bank_transfer, bank_transfer_gmf

Entidad principal: la dispersión (payout). Relacionadas: la cuenta origen y el propietario de la cuenta (account holder).

Recaudos — payin

Entidad principal: el pago. Relacionadas: la cuenta acreditada (la subcuenta) y su propietario.

Transferencias entre subcuentas — account_to_account_fx, account_to_account_fx_spread

Entidad principal: la operación de subcuenta (la transferencia). Relacionadas: la cuenta origen y su propietario.

Entidades relacionadas: cuenta y propietario de la cuenta

Disponibles para todos los tipos de fee anteriores, con el prefijo account. o account_holder.:

La metadata es el gancho más flexible: marca tus cuentas o a sus propietarios con un plan, un segment o un tier al crearlos, y pon precios según eso sin tocar la política cada vez que un usuario cambie de plan.

Ejemplos

Cada ejemplo es una regla dentro de la estrategia de una moneda. Si la operación no cumple las condiciones de la regla, esta no aplica y el precio lo decide la siguiente regla o, cuando ninguna coincide, el default_calculation de la estrategia.

Dispersiones ACH gratis — la regla aplica cuando el método es exactamente co_ach; cualquier otro método paga el default_calculation:

{
  "conditions": [
    { "operator": "equal", "left": { "property": "method" }, "right": { "value": "co_ach" } }
  ],
  "calculation": { "fixed": 0, "percentage": "0" }
}

Una tarifa más baja para dispersiones grandes — desde 1.000.000,00 COP. Este ejemplo muestra la estrategia completa, con el default_calculation que cobra cuando la regla no aplica:

{
  "rules": [
    {
      "summary": "Tarifa reducida desde 1.000.000,00 COP",
      "conditions": [
        {
          "operator": "greater_equal_than",
          "left": { "property": "source_amount" },
          "right": { "value": 100000000 }
        }
      ],
      "calculation": { "fixed": 150000, "percentage": "0" }
    }
  ],
  "default_calculation": { "fixed": 300000, "percentage": "0" }
}

Una dispersión de 1.500.000,00 COP cumple la condición y paga 1.500,00; una de 800.000,00 COP no la cumple, así que paga los 3.000,00 del default_calculation.

Los rieles instantáneos cuestan menos — cualquiera de dos métodos; los demás pagan el default_calculation que para el ejemplo seria un valor mas alto:

{
  "conditions": [
    {
      "operator": "in",
      "left": { "property": "method" },
      "right": { "value": ["co_transfiya", "co_breb"] }
    }
  ],
  "calculation": { "fixed": 120000, "percentage": "0" }
}

Exonerar cuentas VIP — la cuenta se creó con metadata.plan = "vip"; las demás cuentas pagan el default_calculation:

{
  "conditions": [
    {
      "operator": "equal",
      "left": { "property": "account.metadata", "args": { "name": "plan" } },
      "right": { "value": "vip" }
    }
  ],
  "calculation": { "fixed": 0, "percentage": "0" }
}

Las cuentas sin marcar pagan un recargo — el campo de metadata está ausente; las cuentas marcadas pagan el default_calculation:

{
  "conditions": [
    {
      "operator": "is_null",
      "left": { "property": "account.metadata", "args": { "name": "plan" } }
    }
  ],
  "calculation": { "fixed": 200000, "percentage": "0.01" }
}

Las reglas se evalúan en orden y gana la primera que coincide, así que pon primero las más específicas y deja que default_calculation se encargue del resto.

Siguientes pasos

• Políticas de fees — donde viven estas reglas, y cómo se resuelven las políticas.
• Fees — los tipos de fee y por qué se cobra cada uno.
• Crear políticas de fees — el schema completo del request.