Split Payouts

Split payouts allow you to automatically distribute a payment between multiple parties. This is essential for marketplaces, platforms, and any scenario where payments need to be shared among beneficiaries.

Use Cases

• Marketplaces: Split payment between seller and platform fee
• Affiliate Programs: Distribute commissions to affiliates
• Partner Integrations: Share revenue with partners
• Service Platforms: Pay service providers directly

How Split Payouts Work

graph LR
    A[Customer Pays $100] --> B[NjiaPay]
    B --> C[Seller Gets $85]
    B --> D[Platform Gets $15]

When a customer makes a payment with split configuration:

1. Customer pays the full amount
2. NjiaPay processes the payment
3. Payment is automatically split according to your configuration
4. Each beneficiary receives their portion (minus fees for main beneficiary only)

Step 1: Create Beneficiaries

Before using splits, create beneficiaries via API:

curl -X POST https://app.infinic.com/api/merchants/{merchant_id}/beneficiaries \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Seller XYZ",
    "type": "nuban",
    "bank_code": "021",
    "account_number": "0123456789",
    "currency": "NGN",
    "connection_id": "pstck-xxxxx",
    "description": "Marketplace seller payment account"
  }'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Seller XYZ",
  "currency": "NGN",
  "external_id": "recipient_xyz",
  "created": "2024-01-15T10:00:00Z"
}

Store the beneficiary id for use in split requests.

Step 2: Create Payment with Split

Include split configuration when creating a payment intent:

{
  "amount": 10000,
  "currency": "ZAR",
  "reference_id": "marketplace_order_123",
  "purchaser_id": "buyer_456",
  "return_url": "https://yoursite.com/callback",
  "allow_remember_credentials": false,
  "split": {
    "split_type": "AMOUNT",
    "splits": [
      {
        "beneficiary_id": "seller_beneficiary_id",
        "amount": 8500,
        "description": "Seller payment for order 123"
      },
      {
        "beneficiary_id": "main_merchant_id",
        "amount": 1500,
        "description": "Platform fee"
      }
    ],
    "description": "Marketplace transaction split"
  }
}

Important Rules

Amount Validation

The sum of all split amounts MUST equal exactly the total payment amount:

// ✅ Valid - amounts sum to 10000
{
  "amount": 10000,
  "split": {
    "splits": [
      { "amount": 7000 },
      { "amount": 3000 }
    ]
  }
}

// ❌ Invalid - amounts sum to 9000 (mismatch)
{
  "amount": 10000,
  "split": {
    "splits": [
      { "amount": 7000 },
      { "amount": 2000 }
    ]
  }
}

Minimum Splits

You must have at least 2 beneficiaries in a split:

// ✅ Valid - 2 beneficiaries
{ "splits": [beneficiary1, beneficiary2] }

// ❌ Invalid - only 1 beneficiary
{ "splits": [beneficiary1] }

No Duplicate Beneficiaries

Each beneficiary can only appear once:

// ❌ Invalid - same beneficiary twice
{
  "splits": [
    { "beneficiary_id": "abc", "amount": 5000 },
    { "beneficiary_id": "abc", "amount": 3000 }
  ]
}

Currency Matching

All beneficiaries must have the same currency as the payment intent.

Fee Handling

Main Beneficiary (You):

• NjiaPay reserves 3-5% of your split amount to cover external PSP fees
• Example: If your split is 1500, your split is ~1425-1455 (after PSP fees)

Regular Beneficiaries:

• Receive full split amount without fee deductions
• Example: If split is 8500, they receive exactly 8500

This prevents insufficient funds when PSP processes actual fee charges.

Split Lifecycle

After successful payment, splits enter various statuses:

• After successful payment, splits enter "PENDING" status and appear in the portal.
• You can view all split payouts and manually initiate payouts to beneficiaries through the portal.
• Splits progress through processing stages until marked as "COMPLETED" when funds are either transferred or if you have indicated that you have done the payment manually yourself.

Example: Marketplace Integration

// Create order with split
async function createMarketplacePayment(order) {
  const { totalAmount, sellerAmount, platformFee, sellerId, buyerId } = order;

  // Get seller's beneficiary ID
  const sellerBeneficiary = await getBeneficiaryForSeller(sellerId);

  // Create payment with split
  const intent = await createPaymentIntent({
    amount: totalAmount,
    currency: "ZAR",
    reference_id: `order_${order.id}`,
    purchaser_id: buyerId,
    return_url: `https://marketplace.com/orders/${order.id}/complete`,
    allow_remember_credentials: false,
    split: {
      split_type: "AMOUNT",
      splits: [
        {
          beneficiary_id: sellerBeneficiary.id,
          amount: sellerAmount,
          description: `Payment for order ${order.id}`,
        },
        {
          beneficiary_id: PLATFORM_MERCHANT_ID,
          amount: platformFee,
          description: "Platform commission",
        },
      ],
    },
  });

  return intent.redirect_url;
}

Viewing Split Payouts

After payment completes:

1. Log into merchant portal
2. Navigate to Payouts section
3. View all pending/completed splits
4. Manually perform payouts to beneficiaries

Related Topics