Subaccounts

The Subaccounts API allows you create and manage subaccounts on your integration. Subaccounts can be used to split payment between two accounts (your main account and a sub account).

Create Subaccount

Create a subacount on your integration

Headers
authorization String	Set value to `Bearer SECRET_KEY`
content-type String	Set value to `application/json`

Body Parameters
Show optional parameters
business_name String	Name of business for subaccount
settlement_bank String	Bank Code for the bank. You can get the list of Bank Codes by calling the List Banks endpoint.
account_number String	Bank Account Number
percentage_charge Float	The default percentage charged when receiving on behalf of this subaccount
description String	A description for this subaccount
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 String	Stringified JSON object. Add a `custom_fields` attribute which has an array of objects if you would like the fields to be added to your transaction when displayed on the dashboard. Sample: `{"custom_fields":[{"display_name":"Cart ID","variable_name": "cart_id","value": "8393"}]}`

1#!/bin/sh
2url="https://api.paystack.co/subaccount"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6  "business_name": "Sunshine Studios", 
7  "settlement_bank": "044", 
8  "account_number": "0193274682", 
9  "percentage_charge": 18.2 
10}'
11
12curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST

1{
2  "status": true,
3  "message": "Subaccount created",
4  "data": {
5    "integration": 100973,
6    "domain": "test",
7    "subaccount_code": "ACCT_4hl4xenwpjy5wb",
8    "business_name": "Sunshine Studios",
9    "description": null,
10    "primary_contact_name": null,
11    "primary_contact_email": null,
12    "primary_contact_phone": null,
13    "metadata": null,
14    "percentage_charge": 18.2,
15    "is_verified": false,
16    "settlement_bank": "Access Bank",
17    "account_number": "0193274682",
18    "settlement_schedule": "AUTO",
19    "active": true,
20    "migrate": false,
21    "id": 55,
22    "createdAt": "2016-10-05T13:22:04.000Z",
23    "updatedAt": "2016-10-21T02:19:47.000Z"
24  }
25}

List Subaccounts

List subaccounts available on your integration

Headers
authorization String	Set value to `Bearer SECRET_KEY`

Query Parameters
Show optional parameters
perPage Integer	Specify how many records you want to retrieve per page. If not specify we use a default value of 50.
page Integer	Specify exactly what page you want to retrieve. If not specify we use a default value of 1.
from Datetime	A timestamp from which to start listing subaccounts e.g. `2016-09-24T00:00:05.000Z`, `2016-09-21`
to Datetime	A timestamp at which to stop listing subaccounts e.g. `2016-09-24T00:00:05.000Z`, `2016-09-21`

1#!/bin/sh
2url="https://api.paystack.co/subaccount"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X GET

1{
2  "status": true,
3  "message": "Subaccounts retrieved",
4  "data": [
5    {
6      "integration": 129938,
7      "domain": "test",
8      "subaccount_code": "ACCT_cljt3j4cp0kb2gq",
9      "business_name": "Business 2",
10      "description": null,
11      "primary_contact_name": null,
12      "primary_contact_email": null,
13      "primary_contact_phone": null,
14      "metadata": null,
15      "percentage_charge": 20,
16      "is_verified": false,
17      "settlement_bank": "Zenith Bank",
18      "account_number": "0193274382",
19      "active": true,
20      "migrate": false,
21      "id": 53,
22      "createdAt": "2016-10-05T12:55:47.000Z",
23      "updatedAt": "2016-10-05T12:55:47.000Z"
24    },
25    {
26      "integration": 129938,
27      "domain": "test",
28      "subaccount_code": "ACCT_vwy3d1gck2c9gxi",
29      "business_name": "Sunshine Studios",
30      "description": null,
31      "primary_contact_name": null,
32      "primary_contact_email": null,
33      "primary_contact_phone": null,
34      "metadata": null,
35      "percentage_charge": 20,
36      "is_verified": false,
37      "settlement_bank": "Access Bank",
38      "account_number": "0128633833",
39      "active": true,
40      "migrate": false,
41      "id": 35,
42      "createdAt": "2016-10-04T09:06:00.000Z",
43      "updatedAt": "2016-10-04T09:06:00.000Z"
44    },
45    {
46      "integration": 129938,
47      "domain": "test",
48      "subaccount_code": "ACCT_5mikcokeaknxk1f",
49      "business_name": "Business 2",
50      "description": null,
51      "primary_contact_name": null,
52      "primary_contact_email": null,
53      "primary_contact_phone": null,
54      "percentage_charge": 20,
55      "is_verified": false,
56      "settlement_bank": "Access Bank",
57      "account_number": "0000000000",
58      "active": true,
59      "migrate": false,
60      "id": 34,
61      "createdAt": "2016-10-04T08:46:18.000Z",
62      "updatedAt": "2016-10-04T08:46:18.000Z"
63    }
64  ],
65  "meta": {
66    "total": 20,
67    "skipped": 0,
68    "perPage": "3",
69    "page": 1,
70    "pageCount": 7
71  }
72}

Fetch Subaccount

Get details of a subaccount on your integration

Headers
authorization String	Set value to `Bearer SECRET_KEY`

Path Parameters
id_or_code String	The subaccount `ID` or `code` you want to fetch

1#!/bin/sh
2url="https://api.paystack.co/subaccount/:id_or_code"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X GET

1{
2  "status": true,
3  "message": "Subaccount retrieved",
4  "data": {
5    "integration": 100973,
6    "domain": "test",
7    "subaccount_code": "ACCT_4hl4xenwpjy5wb",
8    "business_name": "Sunshine Studios",
9    "description": null,
10    "primary_contact_name": null,
11    "primary_contact_email": "dafe@aba.com",
12    "primary_contact_phone": null,
13    "metadata": null,
14    "percentage_charge": 18.9,
15    "is_verified": false,
16    "settlement_bank": "Access Bank",
17    "account_number": "0193274682",
18    "settlement_schedule": "AUTO",
19    "active": true,
20    "migrate": false,
21    "id": 55,
22    "createdAt": "2016-10-05T13:22:04.000Z",
23    "updatedAt": "2016-10-21T02:19:47.000Z"
24  }
25}

Update Subaccount

Update a subaccount details on your integration

Headers
authorization String	Set value to `Bearer SECRET_KEY`
content-type String	Set value to `application/json`

Path Parameters
id_or_code String	Subaccount's ID or code

Body Parameters
Show optional parameters
business_name String	Name of business for subaccount
settlement_bank String	Bank Code for the bank. You can get the list of Bank Codes by calling the List Banks endpoint.
account_number String	Bank Account Number
active Boolean	Activate or deactivate a subaccount. Set value to `true` to activate subaccount or `false` to deactivate the subaccount.
percentage_charge Float	The default percentage charged when receiving on behalf of this subaccount
description String	A description for this subaccount
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
settlement_schedule String	Any of `auto`, `weekly`, `monthly`, `manual`. Auto means payout is T+1 and manual means payout to the subaccount should only be made when requested. Defaults to `auto`
metadata String	Stringified JSON object. Add a `custom_fields` attribute which has an array of objects if you would like the fields to be added to your transaction when displayed on the dashboard. Sample: `{"custom_fields":[{"display_name":"Cart ID","variable_name": "cart_id","value": "8393"}]}`

1#!/bin/sh
2url="https://api.paystack.co/subaccount/:id_or_code"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6  "primary_contact_email": "dafe@aba.com", 
7  "percentage_charge": 18.9 
8}'
9
10curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X PUT

1{
2  "status": true,
3  "message": "Subaccount updated",
4  "data": {
5    "integration": 100973,
6    "domain": "test",
7    "subaccount_code": "ACCT_4hl4xenwpjy5wb",
8    "business_name": "Sunshine Studios",
9    "description": null,
10    "primary_contact_name": null,
11    "primary_contact_email": "dafe@aba.com",
12    "primary_contact_phone": null,
13    "metadata": null,
14    "percentage_charge": 18.9,
15    "is_verified": false,
16    "settlement_bank": "Access Bank",
17    "account_number": "0193274682",
18    "settlement_schedule": "AUTO",
19    "active": true,
20    "migrate": false,
21    "id": 55,
22    "createdAt": "2016-10-05T13:22:04.000Z",
23    "updatedAt": "2016-10-21T02:19:47.000Z"
24  }
25}