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

authorizationString

Set value to Bearer SECRET_KEY

content-typeString

Set value to application/json

Body Parameters

business_nameString

Name of business for subaccount

bank_codeString

Bank Code for the bank. You can get the list of Bank Codes by calling the List Banks endpoint.

account_numberString

Bank Account Number

percentage_chargeFloat

The percentage the main account receives from each payment made to the subaccount

descriptionStringoptional

A description for this subaccount

primary_contact_emailStringoptional

A contact email for the subaccount

primary_contact_nameStringoptional

A name for the contact person for this subaccount

primary_contact_phoneStringoptional

A phone number to call for this subaccount

metadataStringoptional

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"}]}

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": "Oasis",
7 "settlement_bank": "058",
8 "account_number": "0123456047",
9 "percentage_charge": 30
10}'
11
12curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST
Sample Response
201 Created
1{
2 "status": true,
3 "message": "Subaccount created",
4 "data": {
5 "business_name": "Oasis",
6 "account_number": "0123456047",
7 "percentage_charge": 30,
8 "settlement_bank": "Guaranty Trust Bank",
9 "currency": "NGN",
10 "bank": 9,
11 "integration": 463433,
12 "domain": "test",
13 "account_name": "LARRY JAMES O",
14 "product": "collection",
15 "managed_by_integration": 463433,
16 "subaccount_code": "ACCT_6uujpqtzmnufzkw",
17 "is_verified": false,
18 "settlement_schedule": "AUTO",
19 "active": true,
20 "migrate": false,
21 "id": 1151727,
22 "createdAt": "2024-08-26T09:24:28.723Z",
23 "updatedAt": "2024-08-26T09:24:28.723Z"
24 }
25}

List Subaccounts

List subaccounts available on your integration

Headers

authorizationString

Set value to Bearer SECRET_KEY

Query Parameters

perPageInteger

Specify how many records you want to retrieve per page. If not specify we use a default value of 50.

pageInteger

Specify exactly what page you want to retrieve. If not specify we use a default value of 1.

fromDatetimeoptional

A timestamp from which to start listing subaccounts e.g. 2016-09-24T00:00:05.000Z, 2016-09-21

toDatetimeoptional

A timestamp at which to stop listing subaccounts e.g. 2016-09-24T00:00:05.000Z, 2016-09-21

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 "id": 1151727,
7 "subaccount_code": "ACCT_6uujpqtzmnufzkw",
8 "business_name": "Oasis",
9 "description": "Oasis",
10 "primary_contact_name": null,
11 "primary_contact_email": null,
12 "primary_contact_phone": null,
13 "metadata": null,
14 "percentage_charge": 30,
15 "settlement_bank": "Guaranty Trust Bank",
16 "bank_id": 9,
17 "account_number": "0123456047",
18 "currency": "NGN",
19 "active": 1
20 }
21 ],
22 "meta": {
23 "total": 27,
24 "skipped": 0,
25 "perPage": 50,
26 "page": 1,
27 "pageCount": 1
28 }
29}

Fetch Subaccount

Get details of a subaccount on your integration

Headers

authorizationString

Set value to Bearer SECRET_KEY

Path Parameters

id_or_codeString

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": 463433,
6 "bank": 9,
7 "managed_by_integration": 463433,
8 "domain": "test",
9 "subaccount_code": "ACCT_6uujpqtzmnufzkw",
10 "business_name": "Oasis",
11 "description": null,
12 "primary_contact_name": null,
13 "primary_contact_email": null,
14 "primary_contact_phone": null,
15 "metadata": null,
16 "percentage_charge": 30,
17 "is_verified": false,
18 "settlement_bank": "Guaranty Trust Bank",
19 "account_number": "0123456047",
20 "settlement_schedule": "AUTO",
21 "active": true,
22 "migrate": false,
23 "currency": "NGN",
24 "account_name": "LARRY JAMES O",
25 "product": "collection",
26 "id": 1151727,
27 "createdAt": "2024-08-26T09:24:28.000Z",
28 "updatedAt": "2024-08-26T09:24:28.000Z"
29 }
30}

Update Subaccount

Update a subaccount details on your integration

Headers

authorizationString

Set value to Bearer SECRET_KEY

content-typeString

Set value to application/json

Path Parameters

id_or_codeString

Subaccount's ID or code

Body Parameters

business_nameString

Name of business for subaccount

descriptionString

A description for this subaccount

bank_codeStringoptional

Bank Code for the bank. You can get the list of Bank Codes by calling the List Banks endpoint.

account_numberStringoptional

Bank Account Number

activeBooleanoptional

Activate or deactivate a subaccount. Set value to true to activate subaccount or false to deactivate the subaccount.

percentage_chargeFloatoptional

The default percentage charged when receiving on behalf of this subaccount

primary_contact_emailStringoptional

A contact email for the subaccount

primary_contact_nameStringoptional

A name for the contact person for this subaccount

primary_contact_phoneStringoptional

A phone number to call for this subaccount

settlement_scheduleStringoptional

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

metadataStringoptional

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"}]}

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 "business_name": "Oasis Global",
7 "description": "Provide IT services"
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 "domain": "test",
6 "subaccount_code": "ACCT_6uujpqtzmnufzkw",
7 "business_name": "Oasis Global",
8 "description": "Provide IT services",
9 "primary_contact_name": null,
10 "primary_contact_email": null,
11 "primary_contact_phone": null,
12 "metadata": null,
13 "percentage_charge": 30,
14 "is_verified": false,
15 "settlement_bank": "Guaranty Trust Bank",
16 "account_number": "0123456047",
17 "settlement_schedule": "AUTO",
18 "active": true,
19 "migrate": false,
20 "currency": "NGN",
21 "account_name": "LARRY JAMES O",
22 "product": "collection",
23 "id": 1151727,
24 "integration": 463433,
25 "bank": 9,
26 "managed_by_integration": 463433,
27 "createdAt": "2024-08-26T09:24:28.000Z",
28 "updatedAt": "2024-08-26T09:34:18.000Z"
29 }
30}