Transaction Splits

The TransactionSplitResource enables merchants to split the settlement for a transaction across their payout account and one or more subaccounts. This is useful for marketplaces, split payments between partners, or managing commissions.

Overview

With split payments, you can share your settlement for a transaction with another account. Implementing split payments involves two main steps:

1. Create a Subaccount: Define the account that will receive the split.
2. Initialize a Split Payment: Use the subaccount code when initializing a transaction.

Create Split

Create a split payment configuration on your integration.

$split = paystack()->transactionSplit()->create([
    'name' => 'Halfsies',
    'type' => 'percentage',
    'currency' => 'NGN',
    'subaccounts' => [
        [
            'subaccount' => 'ACCT_6uujpqtzmnufzkw',
            'share' => 50
        ]
    ],
    'bearer_type' => 'all'
]);

Parameters

Parameter	Type	Required	Description
name	String	Yes	Name of the transaction split.
type	String	Yes	The type of transaction split. Options: percentage, flat.
currency	String	Yes	Any of the supported currencies (e.g., NGN, GHS, ZAR, USD).
subaccounts	Array	Yes	A list of objects containing subaccount code and share: [{subaccount: 'ACT_xxx', share: xxx}].
bearer_type	String	Yes	Who bears the transaction charge. Options: subaccount, account, all-proportional, all.
bearer_subaccount	String	No	Subaccount code (required if bearer_type is subaccount).

List Splits

List the transaction splits available on your integration.

// List all splits
$splits = paystack()->transactionSplit()->list();

// Filter splits
$filtered = paystack()->transactionSplit()->list([
    'name' => 'Halfsies',
    'active' => true,
    'perPage' => 20,
    'from' => '2023-01-01',
    'to' => '2023-12-31'
]);

Parameters

Parameter	Type	Description
name	String	Filter by the name of the split.
active	Boolean	Filter by active status (true or false).
sort_by	String	Sort by name. Defaults to createdAt.
perPage	Integer	Number of splits per page. Defaults to 50.
page	Integer	Page number to view. Defaults to 1.
from	Date	A timestamp from which to start listing splits.
to	Date	A timestamp at which to stop listing splits.

Fetch Split

Get details of a specific split on your integration.

$id = '2703655'; // Split ID

$details = paystack()->transactionSplit()->fetch($id);

Update Split

Update a transaction split details on your integration.

$id = '2703655';

$updated = paystack()->transactionSplit()->update($id, [
    'name' => 'Halfsies Updated',
    'active' => true,
    'bearer_type' => 'all-proportional'
]);

Parameters

Parameter	Type	Description
name	String	Name of the transaction split.
active	Boolean	Set to true or false to activate or deactivate the split.
bearer_type	String	Who bears the transaction charge. Options: subaccount, account, all-proportional, all.
bearer_subaccount	String	Subaccount code (required if bearer_type is subaccount).

Add/Update Subaccount Split

Add a Subaccount to a Transaction Split, or update the share of an existing Subaccount in a Transaction Split.

$id = '2703655';

$response = paystack()->transactionSplit()->addSubaccount($id, [
    'subaccount' => 'ACCT_eg4sob4590pq9vb',
    'share' => 20
]);

Parameters

Parameter	Type	Required	Description
subaccount	String	Yes	The subaccount code (e.g., ACCT_xxxxxxxxxx).
share	Integer	Yes	The transaction share for the subaccount.

Remove Subaccount from Split

Remove a subaccount from a transaction split.

$id = '2703655';
$subaccountCode = 'ACCT_eg4sob4590pq9vb';

$response = paystack()->transactionSplit()->removeSubaccount($id, $subaccountCode);

Use Cases

Transaction Splits are powerful for various business models:

1. Marketplaces: Automatically split payments between the platform (you) and the vendor (subaccount).
2. Partnerships: Split revenue between business partners based on a percentage or flat fee.
3. Commissions: Deduct a commission for your platform and settle the rest to the service provider.

Example: Marketplace Split

In this scenario, you want to split a payment where the vendor gets 80% and your platform keeps 20%.

1. Create Subaccount for the vendor (using SubaccountResource).
2. Create Split with the vendor's subaccount and an 80% share.
3. Initialize Transaction using the split_code generated.

// 1. Create Split
$split = paystack()->transactionSplit()->create([
    'name' => 'Vendor Payout',
    'type' => 'percentage',
    'currency' => 'NGN',
    'subaccounts' => [
        ['subaccount' => 'ACCT_VENDOR_123', 'share' => 80]
    ],
    'bearer_type' => 'account' // You bear the Paystack charges
]);

$splitCode = $split['data']['split_code'];

// 2. Initialize Transaction with Split Code
$response = paystack()->transaction()->initialize([
    'email' => '[email protected]',
    'amount' => 10000, // NGN 100.00
    'split_code' => $splitCode
]);

Example: Direct Split (No Split Group)

You can also split a transaction directly without creating a split group by passing the subaccount parameter during initialization.

// Initialize a transaction and split with a specific subaccount
$response = paystack()->transaction()->initialize([
    'email' => '[email protected]',
    'amount' => 20000, // NGN 200.00
    'subaccount' => 'ACCT_xxxxxxxxx',
    // Optional: Override default percentage charge with a flat fee
    'transaction_charge' => 10000, // Main account gets NGN 100.00 flat fee
    // Optional: Specify who bears the transaction fee
    'bearer' => 'subaccount'
]);

Note: When specifying a bearer, ensure the amount going to the subaccount is sufficient to cover the transaction fee, otherwise you will get a 400 Bad Request error.