Subaccounts

The SubaccountResource allows you to create and manage subaccounts on your integration. Subaccounts are essential for splitting payments between your main account and other accounts (e.g., vendors, partners, or branches).

Create Subaccount

Create a subaccount on your integration.

Note: You can get the list of Bank Codes by calling the Miscellaneous Resource listBanks endpoint.

$subaccount = paystack()->subaccount()->create([
    'business_name' => 'Sunshine Studios',
    'settlement_bank' => '058', // Bank Code (e.g., GTBank)
    'account_number' => '0123456047',
    'percentage_charge' => 18.2,
    'description' => 'For my sunshine studios',
    'primary_contact_email' => '[email protected]',
    'primary_contact_name' => 'Dafe',
    'primary_contact_phone' => '08102909304'
]);

Parameters

Parameter	Type	Required	Description
business_name	String	Yes	Name of business for subaccount.
settlement_bank	String	Yes	Bank Code for the bank.
account_number	String	Yes	Bank Account Number.
percentage_charge	Float	Yes	The default percentage charged when receiving on behalf of this subaccount.
description	String	No	A description for this subaccount.
primary_contact_email	String	No	A contact email for the subaccount.
primary_contact_name	String	No	A name for the contact person for this subaccount.
primary_contact_phone	String	No	A phone number to call for this subaccount.
metadata	Array	No	Extra data to configure the subaccount.

List Subaccounts

List subaccounts available on your integration.

// List all subaccounts
$subaccounts = paystack()->subaccount()->list();

// Filter subaccounts
$filtered = paystack()->subaccount()->list([
    'perPage' => 20,
    'page' => 1,
    'from' => '2023-01-01',
    'to' => '2023-12-31'
]);

Parameters

Parameter	Type	Description
perPage	Integer	Specify how many records you want to retrieve per page. Defaults to 50.
page	Integer	Specify exactly what page you want to retrieve. Defaults to 1.
from	Date	A timestamp from which to start listing subaccounts.
to	Date	A timestamp at which to stop listing subaccounts.

Fetch Subaccount

Get details of a subaccount on your integration.

$idOrCode = 'ACCT_4hl4xen0o01p7k3'; // Subaccount ID or Code

$details = paystack()->subaccount()->fetch($idOrCode);

Update Subaccount

Update a subaccount details on your integration.

$idOrCode = 'ACCT_4hl4xen0o01p7k3';

$updated = paystack()->subaccount()->update($idOrCode, [
    'business_name' => 'Sunshine Studios (Updated)',
    'percentage_charge' => 20.0,
    'active' => true,
    'settlement_schedule' => 'weekly'
]);

Parameters

Parameter	Type	Description
business_name	String	Name of business for subaccount.
description	String	A description for this subaccount.
settlement_bank	String	Bank Code for the bank.
account_number	String	Bank Account Number.
active	Boolean	Activate (true) or deactivate (false) a subaccount.
percentage_charge	Float	The default percentage charged when receiving on behalf of this subaccount.
settlement_schedule	String	Any of auto, weekly, monthly, manual. Defaults to auto.
primary_contact_email	String	A contact email for the subaccount.
primary_contact_name	String	A name for the contact person for this subaccount.
primary_contact_phone	String	A phone number to call for this subaccount.
metadata	Array	Extra data to configure the subaccount.

Use Cases

Subaccounts are versatile and can be used in various scenarios:

1. Marketplace Vendors: Create a subaccount for each vendor on your platform. When a customer pays for a product, you can split the payment between your platform and the vendor using Transaction Splits.
2. Franchise Branches: If you run a business with multiple branches, you can create a subaccount for each branch to settle their revenue directly to their specific bank accounts.
3. Partnerships: For joint ventures, you can create subaccounts for partners and split revenue automatically.

Example: Creating a Vendor Subaccount

// 1. Get Bank Code (Optional: You might already have this)
// $banks = paystack()->miscellaneous()->listBanks();

// 2. Create the Subaccount
$vendor = paystack()->subaccount()->create([
    'business_name' => 'Vendor XYZ',
    'settlement_bank' => '058', // GTBank
    'account_number' => '0123456789',
    'percentage_charge' => 10.0, // Platform takes 10%
    'primary_contact_email' => '[email protected]'
]);

$subaccountCode = $vendor['data']['subaccount_code'];

// 3. Use this code in a Transaction Split or directly in a Transaction