Multi-destination transactions allow you to split a single payment across multiple balances. This is perfect for marketplace fees, revenue sharing, referral commissions, and complex payment splits.
Understanding distributions Blnk’s Distribution model lets you define how to split transaction amounts:
Percentage-based : Split by percentage (e.g., “15%”)Fixed amount : Allocate specific amounts (e.g., “50.00”)Remaining amount : Use “left” to assign the remainder
Basic percentage split Split a payment between a merchant and platform fee:
Create transaction with destinations
POST /transactions { "amount" : 100.00 , "precision" : 100 , "reference" : "order_split_001" , "currency" : "USD" , "source" : "bln_customer_wallet" , "destinations" : [ { "identifier" : "bln_merchant_wallet" , "distribution" : "95%" }, { "identifier" : "bln_platform_fee_wallet" , "distribution" : "5%" } ], "description" : "Order payment with 5% platform fee" }
Response with child transactions
{ "transaction_id" : "txn_parent_001" , "amount" : 100.00 , "status" : "APPLIED" , "destinations" : [ { "identifier" : "bln_merchant_wallet" , "distribution" : "95%" , "transaction_id" : "txn_child_001a" }, { "identifier" : "bln_platform_fee_wallet" , "distribution" : "5%" , "transaction_id" : "txn_child_001b" } ] }
Blnk creates:
1 parent transaction (txn_parent_001)
2 child transactions:
txn_child_001a: $95.00 to merchant
txn_child_001b: $5.00 to platform
Fixed amount distributions Allocate specific amounts to each destination:
POST /transactions { "amount" : 100.00 , "precision" : 100 , "reference" : "fixed_split_002" , "currency" : "USD" , "source" : "bln_customer_wallet" , "destinations" : [ { "identifier" : "bln_merchant_wallet" , "distribution" : "80.00" }, { "identifier" : "bln_platform_fee" , "distribution" : "15.00" }, { "identifier" : "bln_processing_fee" , "distribution" : "5.00" } ], "description" : "Payment with fixed fee splits" }
The sum of fixed amounts must not exceed the total transaction amount.
Using “left” for remainders Allocate fixed amounts and assign the remainder:
POST /transactions { "amount" : 100.00 , "precision" : 100 , "reference" : "remainder_split_003" , "currency" : "USD" , "source" : "bln_customer_wallet" , "destinations" : [ { "identifier" : "bln_platform_fee" , "distribution" : "5.00" }, { "identifier" : "bln_processing_fee" , "distribution" : "2.50" }, { "identifier" : "bln_merchant_wallet" , "distribution" : "left" } ], "description" : "Deduct fees, remainder to merchant" }
Result:
Platform fee: $5.00
Processing fee: $2.50
Merchant receives: $92.50 (remaining amount)
Mixing distribution types Combine percentages, fixed amounts, and “left”:
POST /transactions { "amount" : 500.00 , "precision" : 100 , "reference" : "mixed_split_004" , "currency" : "USD" , "source" : "bln_customer_wallet" , "destinations" : [ { "identifier" : "bln_referral_bonus" , "distribution" : "25.00" }, { "identifier" : "bln_platform_fee" , "distribution" : "3%" }, { "identifier" : "bln_merchant_wallet" , "distribution" : "left" } ], "description" : "Fixed referral + percentage fee + remainder" }
Calculation order:
Fixed: $25.00 to referral
Percentage: 3% of 500 = 500 = 500 =
Remainder: 500 − 500 - 500 − 15 = 15 = 15 =
Multi-source transactions Split from multiple sources to a single destination:
POST /transactions { "amount" : 200.00 , "precision" : 100 , "reference" : "multi_source_005" , "currency" : "USD" , "sources" : [ { "identifier" : "bln_wallet_1" , "distribution" : "60%" }, { "identifier" : "bln_wallet_2" , "distribution" : "40%" } ], "destination" : "bln_merchant_wallet" , "description" : "Split payment from two customer wallets" }
Result:
$120 from wallet_1 (60%)
$80 from wallet_2 (40%)
$200 total to merchant
Precise distributions For exact control over minor units, use precise_distribution:
POST /transactions { "amount" : 100.00 , "precision" : 100 , "reference" : "precise_split_006" , "currency" : "USD" , "source" : "bln_customer_wallet" , "destinations" : [ { "identifier" : "bln_merchant" , "precise_distribution" : "9733" }, { "identifier" : "bln_fee" , "precise_distribution" : "267" } ] }
This allocates:
9733 cents ($97.33) to merchant
267 cents ($2.67) to fee
Total: 10000 cents ($100.00)
precise_distribution takes precedence over distribution if both are provided.
Common use cases Marketplace with referral program POST /transactions { "amount" : 1000.00 , "precision" : 100 , "reference" : "marketplace_sale_007" , "currency" : "USD" , "source" : "bln_buyer_wallet" , "destinations" : [ { "identifier" : "bln_seller_wallet" , "distribution" : "85%" }, { "identifier" : "bln_platform_commission" , "distribution" : "10%" }, { "identifier" : "bln_referrer_wallet" , "distribution" : "5%" } ], "description" : "Marketplace sale with referral commission" , "meta_data" : { "order_id" : "order_12345" , "seller_id" : "seller_789" , "referrer_id" : "ref_456" } }
Ride-sharing payment split POST /transactions { "amount" : 50.00 , "precision" : 100 , "reference" : "ride_payment_008" , "currency" : "USD" , "source" : "bln_rider_wallet" , "destinations" : [ { "identifier" : "bln_driver_wallet" , "distribution" : "left" }, { "identifier" : "bln_platform_service_fee" , "distribution" : "15%" }, { "identifier" : "bln_insurance_fund" , "distribution" : "2.00" } ], "description" : "Ride payment split" , "meta_data" : { "ride_id" : "ride_99999" , "driver_id" : "driver_555" } }
Calculation:
Insurance fund: $2.00 (fixed)
Platform fee: 15% of 50 = 50 = 50 =
Driver receives: 50 − 50 - 50 − 7.50 = 7.50 = 7.50 =
POST /transactions { "amount" : 10000.00 , "precision" : 100 , "reference" : "campaign_payout_009" , "currency" : "USD" , "source" : "bln_campaign_escrow" , "destinations" : [ { "identifier" : "bln_creator_wallet" , "distribution" : "left" }, { "identifier" : "bln_platform_fee" , "distribution" : "5%" }, { "identifier" : "bln_payment_processing" , "distribution" : "2.9%" }, { "identifier" : "bln_payment_processing_fixed" , "distribution" : "0.30" } ], "description" : "Campaign funds distribution" }
Breakdown:
Platform fee: 5% of 10 , 000 = 10,000 = 10 , 000 =
Processing percentage: 2.9% of 10 , 000 = 10,000 = 10 , 000 =
Processing fixed: $0.30
Creator receives: 10 , 000 − 10,000 - 10 , 000 − 290 − 290 - 290 −
Distribution calculation (from model/transaction.go:320-376) Blnk’s precise distribution algorithm:
func CalculateDistributionsPrecise ( ctx context . Context , totalPreciseAmount * big . Int , distributions [] Distribution , precision int64 ) ( map [ string ] * big . Int , error ) { // Handle zero amounts if totalPreciseAmount . Cmp ( big . NewInt ( 0 )) == 0 { return handleZeroAmount ( distributions ), nil } state := & distributionState { totalAmountDec : decimal . NewFromBigInt ( totalPreciseAmount , 0 ), amountLeftDec : decimal . NewFromBigInt ( totalPreciseAmount , 0 ), precisionDec : decimal . NewFromInt ( precision ), fixedAmounts : make ( map [ string ] decimal . Decimal ), percentAmounts : make ( map [ string ] decimal . Decimal ), result : make ( map [ string ] * big . Int ), } // Process fixed distributions first processFixedDistributions ( distributions , state ) // Process percentage distributions processPercentageDistributions ( distributions , state ) // Validate total doesn't exceed 100% validateDistributions ( state ) // Adjust for rounding adjustPercentageAmounts ( state ) // Combine all distributions combineDistributions ( state ) // Process "left" distribution processLeftDistribution ( distributions , state ) // Balance to ensure exact total balanceDistributions ( state ) return state . result , nil }
Best practices
Validate totals Ensure percentages don’t exceed 100% and fixed amounts don’t exceed the total.
Use "left" wisely Only one destination should use “left” to avoid conflicts.
Track child transactions Store child transaction IDs for audit trails and reconciliation.
Handle rounding Blnk handles rounding automatically, but be aware of minor unit precision.
Error handling Total exceeds transaction amount { "error" : "total distributions exceed 100% or total amount" }
Multiple “left” distributions { "error" : "multiple identifiers with 'left' distribution" }
{ "error" : "invalid percentage format" }
Next steps
Bulk Transactions Process multiple split payments in batches
Reconciliation Match split payments with external records
