Subaccount

A collection of endpoints for creating and managing accounts for sharing a transaction with

Copy link List Subaccounts

List subaccounts available on your integration

Query Parameters

perPageinteger
Number of records to fetch per request
pageinteger
The offset to retrieve data from
activeboolean
Filter by the state of the subaccounts

Response

200
statusrequiredboolean
messagerequiredstring
datarequiredarray[object]
metarequiredobject
5 object properties
totalrequiredinteger
skippedrequiredinteger
perPagerequiredinteger
pagerequiredinteger
pageCountrequiredinteger
GET/subaccount
curl https://api.paystack.co/subaccount \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
import { Paystack } from "@paystack/paystack-sdk";

const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });

const response = await paystack.subaccount.list({
  perPage: 100,
  page: 100
});
console.log(response.data);
require "paystack"

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

response = paystack.subaccount.list({
  per_page: 100,
  page: 100
})
puts response.data
Response
{
  "status": true,
  "message": "Subaccounts retrieved",
  "data": [
    {
      "id": 1151727,
      "subaccount_code": "ACCT_6uujpqtzmnufzkw",
      "business_name": "Oasis",
      "description": "Oasis",
      "primary_contact_name": null,
      "primary_contact_email": null,
      "primary_contact_phone": null,
      "metadata": null,
      "percentage_charge": 30,
      "settlement_bank": "Guaranty Trust Bank",
      "bank_id": 9,
      "account_number": "0123456047",
      "currency": "NGN",
      "active": 1
    }
  ],
  "meta": {
    "total": 27,
    "skipped": 0,
    "perPage": 50,
    "page": 1,
    "pageCount": 1
  }
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}

Copy link Create Subaccount

Create a subacount for a partner

Request Body

business_namerequiredstring
Name of business for subaccount
settlement_bankrequiredstring
Bank code for the bank. You can get the list of Bank Codes by calling the List Banks endpoint.
account_numberrequiredstring
Bank account number
percentage_chargerequirednumberfloat
Customer's phone number
descriptionstring
A description for this subaccount
primary_contact_emailstring
A contact email for the subaccount
primary_contact_namestring
The name of the contact person for this subaccount
primary_contact_phonestring
A phone number to call for this subaccount
metadatastring
Stringified JSON object of custom data

Response

201
statusrequiredboolean
messagerequiredstring
datarequiredobject
24 object properties
business_namerequiredstring
account_namestring
descriptionrequiredstring
primary_contact_namerequiredstring
primary_contact_emailrequiredstring
primary_contact_phonerequiredstring
metadatarequiredstring
account_numberrequiredstring
percentage_chargerequirednumber
settlement_bankrequiredstring
currencyrequiredstring
bankrequiredinteger
integrationrequiredinteger
domainrequiredstring
productrequiredstring
managed_by_integrationrequiredinteger
subaccount_coderequiredstring
is_verifiedrequiredboolean
settlement_schedulerequiredstring
activerequiredboolean
migraterequiredboolean
idrequiredinteger
createdAtrequiredstring
updatedAtrequiredstring
POST/subaccount
curl https://api.paystack.co/subaccount \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Oasis",
    "settlement_bank": "058",
    "account_number": "0123456047",
    "percentage_charge": 30
  }' \
  -X POST
import { Paystack } from "@paystack/paystack-sdk";

const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });

const response = await paystack.subaccount.create({
  business_name: "Oasis",
  settlement_bank: "058",
  account_number: "0123456047",
  percentage_charge: 30
});
console.log(response.data);
require "paystack"

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

response = paystack.subaccount.create({
  business_name: "Oasis",
  settlement_bank: "058",
  account_number: "0123456047",
  percentage_charge: 30
})
puts response.data
Response
{
  "status": true,
  "message": "Subaccount created",
  "data": {
    "business_name": "Oasis",
    "account_number": "0123456047",
    "percentage_charge": 30,
    "settlement_bank": "Guaranty Trust Bank",
    "currency": "NGN",
    "bank": 9,
    "integration": 463433,
    "domain": "test",
    "account_name": "LARRY JAMES  O",
    "product": "collection",
    "managed_by_integration": 463433,
    "subaccount_code": "ACCT_6uujpqtzmnufzkw",
    "is_verified": false,
    "settlement_schedule": "AUTO",
    "active": true,
    "migrate": false,
    "id": 1151727,
    "createdAt": "2024-08-26T09:24:28.723Z",
    "updatedAt": "2024-08-26T09:24:28.723Z"
  }
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}

Copy link Fetch Subaccount

Get details of a subaccount on your integration

Path Parameters

coderequiredstring
The subaccount code you want to fetch

Response

200
statusrequiredboolean
messagerequiredstring
datarequiredobject
24 object properties
integrationrequiredinteger
account_namestring
bankrequiredinteger
managed_by_integrationrequiredinteger
domainrequiredstring
subaccount_coderequiredstring
business_namerequiredstring
descriptionrequiredstring
primary_contact_namerequiredstring
primary_contact_emailrequiredstring
primary_contact_phonerequiredstring
metadatarequiredstring
percentage_chargerequirednumber
is_verifiedrequiredboolean
settlement_bankrequiredstring
account_numberrequiredstring
settlement_schedulerequiredstring
activerequiredboolean
migraterequiredboolean
currencyrequiredstring
productrequiredstring
idrequiredinteger
createdAtrequiredstring
updatedAtrequiredstring
GET/subaccount/{code}
curl https://api.paystack.co/subaccount/ACCT_6uujpqtzmnufzkw \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
import { Paystack } from "@paystack/paystack-sdk";

const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });

const response = await paystack.subaccount.fetch("ACCT_6uujpqtzmnufzkw");
console.log(response.data);
require "paystack"

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

response = paystack.subaccount.fetch("ACCT_6uujpqtzmnufzkw")
puts response.data
Response
{
  "status": true,
  "message": "Subaccount retrieved",
  "data": {
    "integration": 463433,
    "bank": 9,
    "managed_by_integration": 463433,
    "domain": "test",
    "subaccount_code": "ACCT_6uujpqtzmnufzkw",
    "business_name": "Oasis",
    "description": null,
    "primary_contact_name": null,
    "primary_contact_email": null,
    "primary_contact_phone": null,
    "metadata": null,
    "percentage_charge": 30,
    "is_verified": false,
    "settlement_bank": "Guaranty Trust Bank",
    "account_number": "0123456047",
    "settlement_schedule": "AUTO",
    "active": true,
    "migrate": false,
    "currency": "NGN",
    "account_name": "LARRY JAMES  O",
    "product": "collection",
    "id": 1151727,
    "createdAt": "2024-08-26T09:24:28.000Z",
    "updatedAt": "2024-08-26T09:24:28.000Z"
  }
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}

Copy link Update Subaccount

Update a subaccount details on your integration

Path Parameters

coderequiredstring
The subaccount code you want to fetch

Request Body

business_namestring
Name of business for subaccount
settlement_bankstring
Bank code for the bank. You can get the list of Bank Codes by calling the List Banks endpoint.
account_numberstring
Bank account number
activeboolean
Activate or deactivate a subaccount
percentage_chargenumberfloat
Customer's phone number
descriptionstring
A description for this subaccount
primary_contact_emailstring
A contact email for the subaccount
primary_contact_namestring
The name of the contact person for this subaccount
primary_contact_phonestring
A phone number to call for this subaccount
metadatastring
Stringified JSON object of custom data

Response

200
statusrequiredboolean
messagerequiredstring
datarequiredobject
24 object properties
domainrequiredstring
subaccount_coderequiredstring
account_namestring
business_namerequiredstring
descriptionrequiredstring
primary_contact_namerequiredstring
primary_contact_emailrequiredstring
primary_contact_phonerequiredstring
metadatarequiredstring
percentage_chargerequirednumber
is_verifiedrequiredboolean
settlement_bankrequiredstring
account_numberrequiredstring
settlement_schedulerequiredstring
activerequiredboolean
migraterequiredboolean
currencyrequiredstring
productrequiredstring
idrequiredinteger
integrationrequiredinteger
bankrequiredinteger
managed_by_integrationrequiredinteger
createdAtrequiredstring
updatedAtrequiredstring
PUT/subaccount/{code}
curl https://api.paystack.co/subaccount/ACCT_6uujpqtzmnufzkw \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Sandalwood",
    "settlement_bank": "SETTLEMENT_BANK"
  }' \
  -X PUT
import { Paystack } from "@paystack/paystack-sdk";

const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });

const response = await paystack.subaccount.update("ACCT_6uujpqtzmnufzkw", {
  business_name: "Sandalwood",
  settlement_bank: "SETTLEMENT_BANK"
});
console.log(response.data);
require "paystack"

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

response = paystack.subaccount.update("ACCT_6uujpqtzmnufzkw", {
  business_name: "Sandalwood",
  settlement_bank: "SETTLEMENT_BANK"
})
puts response.data
Response
{
  "status": true,
  "message": "Subaccount updated",
  "data": {
    "domain": "test",
    "subaccount_code": "ACCT_6uujpqtzmnufzkw",
    "business_name": "Oasis Global",
    "description": "Provide IT services",
    "primary_contact_name": null,
    "primary_contact_email": null,
    "primary_contact_phone": null,
    "metadata": null,
    "percentage_charge": 30,
    "is_verified": false,
    "settlement_bank": "Guaranty Trust Bank",
    "account_number": "0123456047",
    "settlement_schedule": "AUTO",
    "active": true,
    "migrate": false,
    "currency": "NGN",
    "account_name": "LARRY JAMES  O",
    "product": "collection",
    "id": 1151727,
    "integration": 463433,
    "bank": 9,
    "managed_by_integration": 463433,
    "createdAt": "2024-08-26T09:24:28.000Z",
    "updatedAt": "2024-08-26T09:34:18.000Z"
  }
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}