SplitRoute Logo
SplitRoute

Payment Distribution

SplitRoute supports flexible payment distribution, allowing you to split payments among multiple recipients. This document explains how payment distribution works and the different distribution types available.

Distribution Types

When creating an invoice, you can specify multiple payment destinations with different distribution types:

Primary Destination

The primary destination receives any remaining funds after other distributions are processed. There can be at most one primary destination per invoice.

JSON
1{
2  "account":  "nano_1abc...",
3  "primary":  true,
4  "description":  "Main recipient"
5}

Percentage-Based Distribution

Percentage-based destinations receive a specified percentage of the total amount.

JSON
1{
2  "account":  "nano_1abc...",
3  "percentage":  25.5,
4  "description":  "Partner fee (25.5%)"
5}

Fixed Amount Distribution

Fixed amount destinations receive a specific amount, regardless of the total invoice amount.

JSON
1{
2  "account":  "nano_1abc...",
3  "amount":  5.00,
4  "description":  "Platform fee ($5.00)"
5}

Equal Split Distribution

Equal split destinations share the total amount equally among all recipients. This is used when no primary destination is specified and all destinations should receive an equal share.

JSON
1{
2  "account":  "nano_1abc...",
3  "distribution_type":  "equal_split",
4  "description":  "Team member 1"
5}

Service Fee

  • A service fee is automatically applied to all payments
  • The fee is calculated as a percentage of the total invoice amount based on your API key tier
  • For Nano payments, the minimum fee is 1 raw unit (when the fee rate is positive)

Distribution Rules

The total payment amount is distributed according to these business rules:

  • Fixed Amount Destinations receive their exact specified amounts
  • Percentage-Based Destinations receive their specified percentage of the total invoice amount
  • Primary Destination receives all remaining funds after other allocations
  • Equal Split Distribution divides funds equally when no primary destination exists

Percentage Allocation Behavior

  • Percentages are calculated based on the total invoice amount
  • If the sum of all percentages would exceed available funds (after accounting for fixed amounts and service fee), percentages are automatically adjusted proportionally
  • This adjustment ensures all recipients receive fair proportional amounts while respecting the distribution constraints

Currency Conversion

  • All payments are processed in Nano's base currency (XNO) raw units
  • Nominal amounts shown in the destinations are approximate
  • Converted amounts are returned with 3 decimal place precision
  • Rounding is performed by rounding to the nearest value, with ties rounded up
  • The exchange rate used for conversions is based on real-time Kraken order book data
  • Specifically, the rate represents the price at which the recipient could sell their Nano for the depth of the invoice created
  • The original raw amounts are used for actual blockchain transactions

Validation Rules

The payment distribution system enforces these validation rules:

  1. Total amount must be greater than zero
  2. At least one destination must exist
  3. Maximum of one primary destination allowed
  4. Total percentage cannot exceed 100%
  5. Total fixed amounts cannot exceed the total invoice amount
  6. Primary destination must have sufficient funds left after other allocations
  7. Service fee rate must be non-negative and not exceed 100%

Example Distribution

Here's an example of how a payment might be distributed:

JSON
1{
2  "nominal_amount":  100.00,
3  "nominal_currency":  "USD",
4  "destinations":  [
5    {
6      "account":  "nano_1abc...",
7      "primary":  true,
8      "description":  "Main recipient"
9    },
10    {
11      "account":  "nano_2def...",
12      "percentage":  20,
13      "description":  "Partner (20%)"
14    },
15    {
16      "account":  "nano_3ghi...",
17      "amount":  10.00,
18      "description":  "Fixed fee ($10.00)"
19    }
20  ]
21}

An invoice for $100.00 USD with these destinations:

  • Primary destination (Main recipient)
  • 20% percentage-based destination (Partner)
  • $10.00 fixed amount destination (Fixed fee)
  • Service fee rate of 0.25%

Would be distributed as:

  1. Service fee: $0.25
  2. Fixed amount: $10.00
  3. Percentage (20%): $20.00
  4. Primary destination: $69.75 (remaining amount)

All amounts would be converted to Nano raw units for actual blockchain transactions.

Error Handling

The API returns clear error messages for various validation failures, including:

  • Invalid distribution configurations
  • Insufficient total amount for percentage distributions
  • Excessive fixed or percentage allocations

Check the API response for detailed error information if your payment distribution setup is rejected.