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
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 percentage the main account receives from each payment made to the 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"}]}
Show optional parameters
POST/subaccount
cURL
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
Sample Response
200 Ok
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
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
Show optional parameters
GET/subaccount
cURL
1#!/bin/sh
2url="https://api.paystack.co/subaccount"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X GET
Sample Response
200 Ok
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
GET/subaccount/:id_or_code
cURL
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
Sample Response
200 Ok
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": "[email protected]",
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
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"}]}
Show optional parameters
PUT/subaccount/:id_or_code
cURL
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": "[email protected]",
7 "percentage_charge": 18.9
8}'
9
10curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X PUT
Sample Response
200 Ok
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": "[email protected]",
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}