rexedge/paystack-subaccounts

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

| Method | Endpoint | Description | | --- | --- | --- | | POST | /subaccount | Create a subaccount | | GET | /subaccount | List subaccounts | | GET | /subaccount/:id_or_code | Fetch a subaccount | | PUT | /subaccount/:id_or_code | Update a subaccount |

Create Subaccount

POST /subaccount

| Param | Type | Required | Description | | --- | --- | --- | --- | | business_name | string | Yes | Name of the sub-merchant business | | bank_code | string | Yes | Bank code (from List Banks endpoint) | | account_number | string | Yes | Bank account number for settlements | | percentage_charge | float | Yes | Percentage the main account receives from each payment | | description | string | No | Description of the subaccount | | primary_contact_email | string | No | Contact email | | primary_contact_name | string | No | Contact person name | | primary_contact_phone | string | No | Contact phone number | | metadata | string | No | Stringified JSON with custom fields |

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: "[email protected]",
  }),
});
// subaccount.data.subaccount_code → "ACCT_6uujpqtzmnufzkw"

List Subaccounts

GET /subaccount

| Param | Type | Required | Description | | --- | --- | --- | --- | | perPage | integer | No | Records per page (default: 50) | | page | integer | No | Page number (default: 1) | | from | datetime | No | Start date | | to | datetime | No | End date |

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

| Param | Type | Required | Description | | --- | --- | --- | --- | | business_name | string | Yes | Business name | | description | string | Yes | Description | | bank_code | string | No | New bank code | | account_number | string | No | New account number | | active | boolean | No | true to activate, false to deactivate | | percentage_charge | float | No | Updated percentage | | settlement_schedule | string | No | auto (T+1), weekly, monthly, or manual | | primary_contact_email | string | No | Updated contact email | | primary_contact_name | string | No | Updated contact name | | primary_contact_phone | string | No | Updated contact phone | | metadata | string | No | Stringified JSON |

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

| Schedule | Description | | --- | --- | | auto | Payout is T+1 (next business day) — default | | weekly | Payout every week | | monthly | Payout every month | | manual | Payout only when requested |

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: "[email protected]",
    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: "[email protected]",
    amount: 100000,
    subaccount: vendor.data.subaccount_code,
    bearer: "subaccount", // Vendor bears Paystack fees
  }),
});
// Platform gets 10%, Vendor gets 90% minus Paystack fees