Paystack Subaccounts

The Subaccounts API lets you create and manage subaccounts for split payments. Subaccounts represent sub-merchants/vendors who receive a portion of each payment.

Depends on: paystack-setup for the paystackRequest helper.
Related: paystack-splits for multi-party split configurations.

Endpoints

Create Subaccount

POST /subaccount

const subaccount = await paystackRequest<{
  subaccount_code: string;
  business_name: string;
  percentage_charge: number;
}>("/subaccount", {
  method: "POST",
  body: JSON.stringify({
    business_name: "Vendor Store",
    settlement_bank: "058",        // GTBank
    account_number: "0123456047",
    percentage_charge: 20,         // Main account gets 20%, subaccount gets 80%
    description: "Electronics vendor",
    primary_contact_email: "vendor@store.com",
  }),
});
// subaccount.data.subaccount_code → "ACCT_6uujpqtzmnufzkw"

List Subaccounts

GET /subaccount

const subaccounts = await paystackRequest("/subaccount?perPage=20&page=1");

Fetch Subaccount

GET /subaccount/:id_or_code

const sub = await paystackRequest(
  `/subaccount/${encodeURIComponent("ACCT_6uujpqtzmnufzkw")}`
);

Update Subaccount

PUT /subaccount/:id_or_code

await paystackRequest(
  `/subaccount/${encodeURIComponent("ACCT_6uujpqtzmnufzkw")}`,
  {
    method: "PUT",
    body: JSON.stringify({
      business_name: "Vendor Store Global",
      description: "International electronics vendor",
      settlement_schedule: "weekly",
      percentage_charge: 15,
    }),
  }
);

Settlement Schedules

Using Subaccounts in Transactions

Pass the subaccount code when initializing a transaction:

// Initialize transaction with subaccount split
const tx = await paystackRequest("/transaction/initialize", {
  method: "POST",
  body: JSON.stringify({
    email: "customer@email.com",
    amount: 500000,
    subaccount: "ACCT_6uujpqtzmnufzkw",
    // Optional overrides:
    // transaction_charge: 10000,  // Fixed charge in subunits (overrides percentage)
    // bearer: "subaccount",       // Who bears Paystack fees: "account" or "subaccount"
  }),
});

Marketplace Pattern

// 1. Onboard vendor → create subaccount
const vendor = await paystackRequest("/subaccount", {
  method: "POST",
  body: JSON.stringify({
    business_name: "Vendor A",
    settlement_bank: "058",
    account_number: "0123456789",
    percentage_charge: 10, // Platform takes 10%
  }),
});

// 2. Customer buys from vendor → charge with subaccount
await paystackRequest("/transaction/initialize", {
  method: "POST",
  body: JSON.stringify({
    email: "buyer@email.com",
    amount: 100000,
    subaccount: vendor.data.subaccount_code,
    bearer: "subaccount", // Vendor bears Paystack fees
  }),
});
// Platform gets 10%, Vendor gets 90% minus Paystack fees