Fee policies

A fee policy is the pricing rule behind a fee: it says how much to charge for one kind of fee and whom the price applies to. You keep a general price for every account of your users or customers and override it wherever you need — a program with its own plan, an enterprise client with negotiated terms, a single account you want to exempt. When a fee is charged, Mono picks the most specific policy that covers the account and applies it.

Policies replace the need to ask Mono every time your pricing changes. You create, adjust, skip (pause) and remove them through the API, and you can always check which policy an account ends up with — and why.

Before you start

You will need:

• A Core API key with the fees scope (fees:readonly is enough to read policies and fees).
• Core fee policies enabled for you as a tenant. Mono enables them and creates your base policies — one per fee type in use — when you onboard.
• To know your programs, account holders and accounts by their identifiers (pro_, acch_, lacc_): they are what a policy targets.

Anatomy of a policy

Who a policy applies to

A policy targets one of four levels. From the least to the most specific:

1. tenant — the base or global policy. It covers every account of your users or customers and is the price of last resort.
2. program — every account in a program.
3. account_holder — every account of a single account holder: one of your users or customers.
4. account — a single subaccount.

When a fee is charged on an account, Mono looks at the policies of that fee type that cover the account — its own, its holder's, its program's and the base or global one (tenant) — and applies the most specific one that is not skipped or paused:

tenant                     the base or global policy — always exists, default price
└── program                overrides it for every account of the program
    └── account_holder     overrides both for every account of the holder
        └── account        overrides everything for this account only

Three rules complete the picture:

• Only one active policy per fee type and target. To change the price of a program, a holder or an account that already has a policy, update it; creating a second one is rejected.
• The base policy always exists. Mono creates your base or global (tenant) policies. You can update them, but not create, skip (pause) or delete them — they guarantee every fee has a price.
• A policy only covers the currencies it includes. If an account's currency is not among the policy's strategies, that policy does not apply to it and the next less specific one does.

Which currencies a policy must cover

The currencies in strategies must stay within the ones the target supports:

A program or account_holder policy can therefore price only one currency and leave the others to the base policy — useful when a plan differs in COP but not in USD.

Seeing which policy applies

GET /v1/ledger/accounts/{account_id}/fees/policies lists, for a subaccount, every policy that bears on it, grouped by fee type and ordered from the most to the least specific, with applied: true on the one that wins. Skipped (paused) policies appear with applied: false, so you can see why a policy is not taking effect. Use it after creating or skipping a policy to confirm the result.

How the price is calculated

Each currency in strategies has its own strategy: an ordered list of rules (rules) and a default calculation (default_calculation). Mono evaluates the rules in order and uses the calculation of the first one whose conditions all hold; if none matches, it uses the default calculation. A strategy with no rules always uses the default calculation, which is the simplest way to set a flat price.

Calculation

A calculation is a fixed amount plus a percentage of the amount of the operation:

Both parts are always explicit — send 0 and "0" for the parts you do not charge — so a fee is never priced at zero by omission.

For example, on a COP payout of 2.000.000,00, a calculation with fixed: 90000, percentage: "0.004", percentage_mode: "capped" and percentage_limit: 500000 charges 900,00 fixed plus 8.000,00 variable (0.4%); with a larger payout, the variable part would stop growing at 5.000,00.

Rules and conditions

A rule applies its calculation when all of its conditions hold. Conditions compare a property of the operation — its method, its amount, its currency, a metadata field of the account — against a value or another property. This is how you price a payout rail differently, give a discount above an amount or exempt accounts tagged in a certain way. The full list of operators and of the properties each fee type can look at lives in Conditions.

Fee types and their processing

Each fee type allows specific values of processing_type and processing_subtype for the fees you charge:

Managing policies

A few things to know about each operation:

• Creating. Send the policies under policies, always a list (up to 50). The batch is atomic: if one policy is rejected, none is created, and the error's path points at the item and field that failed — /policies/1/strategies/COP reads "the COP strategy of the second policy". A new policy never starts out skipped (paused).
• Updating. Only the fields you send change. strategies is replaced as a whole, so send every currency the policy must keep; removing a currency is sending the map without it. fee_type, target_type and target_id are immutable — to move a policy, delete it and create a new one. Changes apply to the fees charged from then on; fees already charged keep their price.
• Skipping or pausing. skip: true skips (pauses) a policy: the next less specific one takes over until you set skip back to false. Base policies cannot be skipped.
• Deleting. The policy stops applying and disappears from the listings, and its target and fee type are free for a new policy. Base policies cannot be deleted. Fees already charged keep referencing the deleted policy.

Example: a special price for one program

A program of premium users pays a lower payout fee, and nothing at all for ACH payouts:

{
  "policies": [
    {
      "fee_type": "bank_transfer",
      "summary": "Premium program — bank transfer fee",
      "transaction_description": "Transfer fee",
      "target_type": "program",
      "target_id": "pro_3rbnHF9AtEBSyyfqZAmnii",
      "processing_type": "inline",
      "processing_subtype": "add_posting",
      "strategies": {
        "COP": {
          "rules": [
            {
              "summary": "ACH payouts are free",
              "conditions": [
                {
                  "operator": "equal",
                  "left": { "property": "method" },
                  "right": { "value": "co_ach" }
                }
              ],
              "calculation": { "fixed": 0, "percentage": "0" }
            }
          ],
          "default_calculation": { "fixed": 300000, "percentage": "0" }
        }
      }
    }
  ]
}

From then on, every COP payout from an account of that program costs 3.000,00 — except ACH payouts, which cost nothing — while accounts in your other programs keep the price of your base policy.

Errors

Business errors come with an error_code and, when they concern one item of a batch, a path locating it:

Next steps

• Conditions — every operator and property available to your rules.
• Fees — what happens once a policy has priced a fee.
• Fees API reference — request and response payloads in full.