Payment Distribution Rules

SplitRoute allows you to automatically split incoming payments among multiple destinations. This guide explains how to set up distribution rules, how the final amounts are calculated, and what configurations are valid.

How it Works: The Calculation Waterfall

SplitRoute processes distributions in a specific order, like a waterfall. The amount available for each step depends on the deductions made in previous steps:

Service Fee (0.5%): A standard 0.5% service fee is calculated on the total incoming amount and deducted first. Depending on your tier this fee can be reduced further.
Fixed Amounts: Destinations set with a specific nominal_amount (e.g., $10.00) are allocated next from the pool remaining after the fee.
Percentage Amounts: Destinations set with a percentage receive their share based on the pool remaining after fees and fixed amounts have been deducted.
Primary Destination: The destination marked as primary receives whatever is left at the end.

Important: Percentage calculations are based on the remaining balance at that point in the waterfall, not the original total amount.

(Internally, all calculations use the cryptocurrency's base units, like Nano raw, for accuracy. Final amounts are converted back to the nominal currency for display.)

Distribution Types Explained

You define how each recipient gets paid using these types:

Primary (`primary: true`)

Gets: The final remainder after all other deductions (Fee, Fixed, Percentage).
Limit: Only one primary destination allowed per configuration.
Use For: Your main wallet or the recipient intended to receive the bulk of the funds after specific payouts.
Setup: {"account": "...", "primary": true}

Fixed Amount (`nominal_amount`)

Gets: A specific target amount in the invoice currency (e.g., USD).
Limit: The sum of all fixed amounts cannot exceed the invoice's total nominal amount (if specified). Exceeding this limit will raise an exception.
Validation: Fixed amounts must not exceed the invoice total amount. The validation will raise an exception if the sum of fixed amounts exceeds the invoice total.
Setup: {"account": "...", "nominal_amount": "15.00", "description": "Service subscription"}

Percentage (`percentage`)

Gets: A percentage of the amount remaining after fees and fixed payouts.
Limit: The sum of all percentages cannot exceed 100%. Exceeding 100% will raise an exception.
Setup: {"account": "...", "percentage": "10.5", "description": "Partner share (10.5%)"}

Special Case: Inferring Total from Fixed Rules

If you only use Fixed Amount destinations and do not provide a total invoice_nominal_amount:

The system treats the sum of your fixed amounts as the effective total for calculation purposes.
The 0.5% service fee will be calculated based on this inferred total.
This is useful if the invoice purpose is the sum of specific fixed payouts.

Examples

(Using 0.5% Service Fee)

Scenario 1: Simple Split

Invoice Total: $100.00
Rules:
- { account: A, percentage: "20" }
- { account: B, primary: true }
Calculation Steps:
1. Fee: $100.00 * 0.5% = $0.50. (Remaining: $99.50)
2. Fixed: $0. (Remaining: $99.50)
3. Percentage (A): 20% of $99.50 = $19.90. (Remaining: $79.60)
4. Primary (B): Gets $79.60.
Result: Fee($0.50), A($19.90), B($79.60)

Scenario 2: Mixed Types

Invoice Total: $100.00
Rules:
- { account: A, nominal_amount: "10.00" } (Fixed)
- { account: B, percentage: "50" }
- { account: C, primary: true }
Calculation Steps:
1. Fee: $0.50. (Remaining: $99.50)
2. Fixed (A): Gets $10.00. (Remaining: $89.50)
3. Percentage (B): 50% of $89.50 = $44.75. (Remaining: $44.75)
4. Primary (C): Gets $44.75.
Result: Fee($0.50), A($10.00), B($44.75), C($44.75)

Scenario 3: Fixed Amount Invalid Configuration

Invoice Total: $50.00
Rules:
- { account: A, nominal_amount: "30.00" } (Fixed)
- { account: B, nominal_amount: "30.00" } (Fixed)
Validation:
1. Sum of fixed amounts ($60.00) exceeds invoice total ($50.00)
2. This violates the validation rule: "Sum of fixed destination amounts cannot exceed the provided total invoice amount"
Result: Validation error is raised, configuration rejected

Scenario 4: Inferring Total

Invoice Total: Not Provided
Rules:
- { account: A, nominal_amount: "80.00" } (Fixed)
- { account: B, nominal_amount: "20.00" } (Fixed)
Calculation Steps:
1. Inferred Total: $80.00 + $20.00 = $100.00.
2. Fee: $100.00 * 0.5% = $0.50. (Remaining: $99.50)
3. Fixed: Required $100.00, Available $99.50. Amounts reduced proportionally.
4. Primary: N/A.
Result: Fee($0.50), A(~~$79.60), B(~~$19.90) (Exact amounts by proportional split of $99.50 based on $80/$20 ratio)

Configuration Validation

To prevent errors, SplitRoute checks your rules when you save them:

Required: Must have at least one destination. Valid account addresses are needed.
Primary: Max one destination with primary: true. Primary cannot have percentage or nominal_amount.
Type Exclusivity: Cannot set both percentage and nominal_amount on the same destination.
Fixed Sum: If an invoice_nominal_amount is set, the sum of all fixed nominal_amount rules cannot exceed it. Exceeding this limit will raise an exception.
Percentage Sum: The sum of all percentage rules cannot exceed 100%. Exceeding 100% will raise an exception.
No Primary Rule: If you don't set a primary destination:
- All destinations must be of the same type. Mixed types without a primary destination will raise an exception.
- If all are Percentage type, they must sum to exactly 100%. Not totaling exactly 100% will raise an exception.
- OR All must be Fixed Amount:
  - If invoice_nominal_amount is provided, they must sum exactly to the invoice total amount.
  - If invoice_nominal_amount is not provided, the total is inferred from the sum of fixed amounts.

Need Help?

If you receive an API error when setting up rules, check the message against the Configuration Validation rules above. If the distribution results seem unexpected, review the Calculation Waterfall and Examples to understand the allocation order. Contact support or join our Discord if you have further questions.