Split Payments

Automatically distribute incoming payments to multiple parties. Perfect for marketplaces, platform fees, and revenue sharing arrangements.

Overview

The Split Payments API enables automatic distribution of funds when payments are received. Use cases include:

Marketplace commission collection
Platform fees for SaaS applications
Revenue sharing with partners
Automatic tax or fee deductions
Multi-vendor order payments

Split Types

Type	Description	Example
`PERCENTAGE`	Split as percentage of payment	15% platform fee
`FIXED`	Fixed amount per transaction	KES 50 processing fee
`REMAINDER`	Receives remaining after other splits	Vendor gets the rest

How It Works

Create Configuration: Define split rules for a merchant
Receive Payment: Customer pays the merchant
Auto-Split: Funds are automatically distributed per rules
Webhooks: All parties receive notifications

Example Split

For a KES 10,000 payment with 15% platform fee and KES 100 processing fee:

Recipient	Type	Value	Amount
Platform	PERCENTAGE	15%	KES 1,500
Processor	FIXED	100	KES 100
Merchant	REMAINDER	-	KES 8,400

API Reference

Create Split Configuration

Create a new split configuration for a merchant.

Expand

Code Examples

Setup Marketplace Split (JavaScript)

setup-split.js

1async function setupMarketplaceSplit(merchantId, platformWalletId, feePercentage) {
2  const API_KEY = process.env.WASAAPAY_API_KEY;
3  const BASE_URL = 'https://api.wasaapay.com/api/v1/partner';
4
5  const response = await fetch(`${BASE_URL}/split-configs`, {
6    method: 'POST',
7    headers: {
8      'Content-Type': 'application/json',
9      'X-API-Key': API_KEY,
10      'X-Idempotency-Key': `split_${merchantId}_${Date.now()}`,
11    },
12    body: JSON.stringify({
13      merchantId: merchantId,
14      name: `Marketplace Split - ${feePercentage}%`,
15      rules: [
16        {
17          recipientType: 'PLATFORM',
18          recipientWalletId: platformWalletId,
19          splitType: 'PERCENTAGE',
20          percentage: feePercentage / 100, // Convert to decimal
21          priority: 0
22        },
23        {
24          recipientType: 'MERCHANT',
25          splitType: 'REMAINDER',
26          priority: 1
27        }
28      ],
29      metadata: {
30        setupDate: new Date().toISOString(),
31        feeStructure: 'percentage'
32      }
33    }),
34  });
35
36  const result = await response.json();
37
38  if (!result.success) {
39    throw new Error(result.message);
40  }
41
42  console.log(`Split config created: ${result.data.id}`);
43  console.log(`Platform receives ${feePercentage}% of each payment`);
44
45  return result.data;
46}
47
48// Setup 15% platform fee for a merchant
49setupMarketplaceSplit('merchant_seller123', 'wallet_platform', 15)
50  .then(config => console.log('Config ID:', config.id))
51  .catch(console.error);

Multi-Party Split Example

multi-party-split.js

1// Complex split: Platform fee + Referrer commission + Merchant remainder
2const multiPartySplit = {
3  merchantId: "merchant_xyz",
4  name: "Affiliate Program Split",
5  rules: [
6    {
7      recipientType: "PLATFORM",
8      recipientWalletId: "wallet_platform",
9      splitType: "PERCENTAGE",
10      percentage: 0.10, // 10% platform fee
11      priority: 0
12    },
13    {
14      recipientType: "REFERRER",
15      recipientWalletId: "wallet_affiliate123",
16      splitType: "PERCENTAGE",
17      percentage: 0.05, // 5% referrer commission
18      priority: 1
19    },
20    {
21      recipientType: "PROCESSING",
22      recipientWalletId: "wallet_processor",
23      splitType: "FIXED",
24      fixedAmount: 50, // KES 50 processing fee
25      priority: 2
26    },
27    {
28      recipientType: "MERCHANT",
29      splitType: "REMAINDER", // Gets the rest
30      priority: 3
31    }
32  ]
33};
34
35// For a KES 1,000 payment:
36// - Platform: KES 100 (10%)
37// - Referrer: KES 50 (5%)
38// - Processing: KES 50 (fixed)
39// - Merchant: KES 800 (remainder)

Webhooks

Receive notifications when split payments are processed. See Webhooks documentation for setup.

Split Payment Events

Event	Description
`split_payment.created`	Split payment initiated
`split_payment.completed`	All distributions completed
`split_payment.failed`	Split distribution failed
`split_distribution.completed`	Individual distribution completed

Event

Description

split_payment.created

Split payment initiated

split_payment.completed

All distributions completed

split_payment.failed

Split distribution failed

split_distribution.completed

Individual distribution completed

Best Practices

Use REMAINDER for merchants: Always use REMAINDER type for the merchant to receive whatever is left after fees

Set priorities carefully: Fixed fees should typically have higher priority than percentages

Test with small amounts: Verify split calculations with test transactions before going live

Monitor distributions: Track split payments to ensure correct distribution

Handle edge cases: Consider minimum amounts to avoid splits that result in zero distributions

Split Payments

Overview

Split Types

How It Works

Example Split

API Reference

Create Split Configuration

Get Split Configuration

List Split Configurations

Update Split Configuration

Delete Split Configuration

Get Split Payment