Documentação

English

Português
Español

English

Português
Español

Appearance

Waterfall Templates ​

Access prerequisites

  • Permission (module): creditConfigManage (to create/edit). Read access granted by viewCredits.
  • License/Feature: CREDIT_INVESTMENTS enabled in the tenant license (Vault).
  • Menu container: TOKENIZATION → Tokenized Credit group

What it is / when to use ​

The Waterfall Template defines the distribution order of funds when a receivable is settled. It specifies, step by step, who receives first and under what rule: first the investor's principal, then the investor's yield, the platform fee, any originator excess, and the reserve. It is the mechanism that ensures the payment waterfall always follows the same contracted priority.

Use this screen to standardize how settled funds are split among parties at settlement, instead of defining the order case by case.

Prerequisites ​

  • Permission: creditConfigManage (dual permission — CPM enum + dynamic module in DB).
  • License/Feature: CREDIT_INVESTMENTS enabled.
  • Dependencies: none to create the template; it is consumed at the settlement of an operation.

Step by step ​

  1. Go to Tokenized Credit → Waterfall Templates.
  2. Filter by Active if needed.
  3. Click Create.
  4. Fill in Name, Reserve %, and the Rounding Rule.
  5. In the Steps block, click Add step and configure each row: Item Type, Rule Type, and, if applicable, the Value. The order is numbered automatically (first step = highest priority).
  6. Reorder by removing/re-adding steps (renumbering is automatic).
  7. Click Save.

Fields ​

FieldWhat it isRequired?System/backend effect
NameTemplate identifierYesStored in name.
Reserve %Percentage retained as reserve before/during the waterfallNo (default 0)Stored in reservePercentage.
Rounding RuleHow to round fractional amounts: FLOOR (round down, 10.9→10), CEIL (round up, 10.1→11), ROUND (nearest)NoStored in roundingRule (or null if empty). Ensures cent consistency when splitting among parties.
Step → OrderPosition in the distribution queueYes (automatic)Stored in order. At execution, items are sorted by priority (lowest first) and disbursements occur in that sequence.
Step → Item TypeWho/what the step pays: INVESTOR_PRINCIPAL, INVESTOR_YIELD, PLATFORM_FEE, ORIGINATOR_EXCESS, RESERVEYesStored in itemType. Routes the disbursement to the correct account and classifies the ledger entry (INVESTOR, PLATFORM, or ORIGINATOR).
Step → Rule TypeHow the step amount is calculated: PERCENT, FIXED, or REMAINDERYesStored in rule.type. PERCENT/FIXED use the Value; REMAINDER distributes whatever is left (no Value).
Step → ValuePercentage (PERCENT) or amount (FIXED)ConditionalStored in rule.value. Omitted when the type is REMAINDER.
ActiveEnables/disables the templateYes (default Yes)Stored in active.
VersionVersion numberNo (default 1)Stored in version.

The form automatically builds the stepsJson (structure { steps: [{ order, itemType, rule: { type, value } }] }). You do not edit the JSON manually.

How the waterfall is executed (executor view) ​

At settlement, the waterfall executor:

  1. Locates the Escrow Pool account (platform guarantee pool).
  2. Sorts items by priority (lowest number first).
  3. For each item, releases funds from the Escrow Pool to the destination account and records the ledger entry with an idempotencyKey per settlement+itemType.
  4. If an item fails, the executor continues with the next ones (does not abort the entire waterfall).

Actions and modals ​

  • Create / Update: saves the template via createWaterfallTemplate / updateWaterfallTemplate. Button visible only with creditConfigManage.
  • Add / Remove step: manipulate the list and automatically renumber the order.
  • Edit: loads the template and rebuilds the steps from the saved stepsJson.

Because it defines how money is split, saving may require step-up (password + MFA) depending on the environment.

Business rules / cautions ​

Attention

  • Order is priority. Whoever is on top receives first. Always place INVESTOR_PRINCIPAL before INVESTOR_YIELD, and both before PLATFORM_FEE/ORIGINATOR_EXCESS, unless a specific contract dictates otherwise.
  • Use REMAINDER in the last step. The REMAINDER step distributes the remaining balance; placing it in the middle may zero out subsequent steps. Normally ORIGINATOR_EXCESS is REMAINDER.
  • REMAINDER ignores the Value. Even if you enter a value, it is not stored for REMAINDER steps.
  • Partial failure does not revert disbursements already made. The executor proceeds to the next item; a failed item remains pending without undoing previous ones — requires manual reconciliation.

Financial distribution

  • Waterfall execution moves real money from the Escrow Pool to investors/platform/originator. Once a disbursement is released, there is no automatic rollback — a wrong template distributes incorrectly. Validate the order and values before activating.
  • Financial values: percentages and amounts are handled as BigNumber; the Rounding Rule explicitly defines how fractional cents are treated to avoid reconciliation discrepancies.
  • Idempotency: disbursements are recorded with an idempotencyKey per settlement+itemType — reprocessing a settlement is safe and does not duplicate ledger entries. In ecosystem financial flows, error E00021 ("already processed") means success (already processed), not failure.

Examples ​

Scenario 1 — Standard investor-first waterfall
  1. Name: "Senior Standard". Reserve %: 0. Rounding: FLOOR.
  2. Steps:
    • 1 · INVESTOR_PRINCIPAL · REMAINDER — returns the invested principal.
    • 2 · INVESTOR_YIELD · PERCENT · value per contracted yield.
    • 3 · PLATFORM_FEE · PERCENT · platform fee.
    • 4 · ORIGINATOR_EXCESS · REMAINDER — whatever remains goes back to the originator.
  3. Save.

Note: if there are two REMAINDER steps, the first consumes the balance; adjust to use FIXED/PERCENT for the principal and reserve REMAINDER only for the originator excess.

Scenario 2 — Waterfall with reserve and fixed fee
  1. Name: "With 5% Reserve". Reserve %: 5. Rounding: ROUND.
  2. Steps:
    • 1 · RESERVE · PERCENT · 5.
    • 2 · INVESTOR_PRINCIPAL · FIXED · principal amount.
    • 3 · INVESTOR_YIELD · PERCENT · yield.
    • 4 · PLATFORM_FEE · FIXED · fixed fee.
    • 5 · ORIGINATOR_EXCESS · REMAINDER.
  3. Save.

Result: at settlement, 5% goes to reserve, investor principal and yield are paid next, the platform receives the fixed fee, and the remaining balance returns to the originator.

Scenario 3 — "Subordinated originator" waterfall
  1. Name: "Subordinated Originator". Rounding: FLOOR.
  2. Steps: INVESTOR_PRINCIPAL → INVESTOR_YIELD → PLATFORM_FEE → ORIGINATOR_EXCESS (REMAINDER).
  3. Save.

Result: the originator only receives excess after all investors and the platform — a typical structure for operations where the originator absorbs the first loss.