Transaction Splits

The Transaction Splits API enables merchants split the settlement for a transaction across their payout account, and one or more subaccounts.

Create Split

Create a split payment on your integration

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

Body Parameters
name String	Name of the transaction split
type String	The type of transaction split you want to create. You can use one of the following: percentage \| flat
currency String	Any of the supported currency
subaccounts Array	A list of object containing subaccount code and number of shares: `[{subaccount: ‘ACT_xxxxxxxxxx’, share: xxx},{...}]`
bearer_type String	Any of subaccount \| account \| all-proportional \| all
bearer_subaccount String	Subaccount code

1#!/bin/sh
2url="https://api.paystack.co/split"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6  "name":"Percentage Split", 
7  "type":"percentage", 
8  "currency": "NGN",
9  "subaccounts":[{
10    "subaccount": "ACCT_z3x6z3nbo14xsil",
11    "share": 20
12  },
13  {
14    "subaccount": "ACCT_pwwualwty4nhq9d",
15    "share": 30
16  }], 
17  "bearer_type":"subaccount", 
18  "bearer_subaccount":"ACCT_hdl8abxl8drhrl3"
19}'
20
21curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST

1{
2  "status": true,
3  "message": "Split created",
4  "data": {
5    "id": 142,
6    "name": "Test Doc",
7    "type": "percentage",
8    "currency": "NGN",
9    "integration": 428626,
10    "domain": "test",
11    "split_code": "SPL_e7jnRLtzla",
12    "active": true,
13    "bearer_type": "subaccount",
14    "bearer_subaccount": 40809,
15    "createdAt": "2020-06-30T11:42:29.150Z",
16    "updatedAt": "2020-06-30T11:42:29.150Z",
17    "subaccounts": [
18      {
19        "subaccount": {
20          "id": 40809,
21          "subaccount_code": "ACCT_z3x6z3nbo14xsil",
22          "business_name": "Business Name",
23          "description": "Business Description",
24          "primary_contact_name": null,
25          "primary_contact_email": null,
26          "primary_contact_phone": null,
27          "metadata": null,
28          "percentage_charge": 20,
29          "settlement_bank": "Business Bank",
30          "account_number": "1234567890"
31        },
32        "share": 20
33      },
34      {
35        "subaccount": {
36          "id": 40809,
37          "subaccount_code": "ACCT_pwwualwty4nhq9d",
38          "business_name": "Business Name",
39          "description": "Business Description",
40          "primary_contact_name": null,
41          "primary_contact_email": null,
42          "primary_contact_phone": null,
43          "metadata": null,
44          "percentage_charge": 20,
45          "settlement_bank": "Business Bank",
46          "account_number": "0123456789"
47        },
48        "share": 30
49      }
50    ],
51    "total_subaccounts": 2
52  }
53}

List Split

List the transaction splits available on your integration

Headers
authorization String	Set value to `Bearer SECRET_KEY`

Query Parameters
Show optional parameters
name String	The name of the split
active Boolean	Any of true or false
sort_by String	Sort by name, defaults to createdAt date
perPage Integer	Number of splits per page. If not specify we use a default value of 50.
page Integer	Page number to view. If not specify we use a default value of 1.
from Datetime	A timestamp from which to start listing splits e.g. `2019-09-24T00:00:05.000Z`, `2019-09-21`
to Datetime	A timestamp at which to stop listing splits e.g. `2019-09-24T00:00:05.000Z`, `2019-09-21`

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

1{
2  "status": true,
3  "message": "Split retrieved",
4  "data": [
5    {
6      "id": 143,
7      "name": "Test Doc",
8      "split_code": "SPL_UO2vBzEqHW",
9      "integration": 428626,
10      "domain": "test",
11      "type": "percentage",
12      "active": 1,
13      "currency": "NGN",
14      "bearer_type": "subaccount",
15      "bearer_subaccount": 40809,
16      "created_at": "2020-06-30T11:52:24.000Z",
17      "updated_at": "2020-06-30T11:52:24.000Z",
18      "subaccounts": [
19        {
20          "subaccount": {
21            "id": 40809,
22            "subaccount_code": "ACCT_z3x6z3nbo14xsil",
23            "business_name": "Business Name",
24            "description": "Business Description",
25            "primary_contact_name": null,
26            "primary_contact_email": null,
27            "primary_contact_phone": null,
28            "metadata": null,
29            "percentage_charge": 80,
30            "settlement_bank": "Business Bank",
31            "account_number": "1234567890"
32          },
33          "share": 30
34        },
35        {
36          "subaccount": {
37            "id": 40811,
38            "subaccount_code": "ACCT_pwwualwty4nhq9d",
39            "business_name": "Business Name",
40            "description": "Business Description",
41            "primary_contact_name": null,
42            "primary_contact_email": null,
43            "primary_contact_phone": null,
44            "metadata": null,
45            "percentage_charge": 80,
46            "settlement_bank": "Business Bank",
47            "account_number": "0123456789"
48          },
49          "share": 20
50        }
51      ],
52      "total_subaccounts": 2
53    }
54  ],
55  "meta": {
56    "total": 1,
57    "skipped": 0,
58    "perPage": 50,
59    "page": 1,
60    "pageCount": 1
61  }
62}

Fetch Split

Get details of a split on your integration

Headers
authorization String	Set value to `Bearer SECRET_KEY`

Path Parameters
id String	The id of the split

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

1{
2  "status": true,
3  "message": "Split retrieved",
4  "data": {
5    "id": 143,
6    "name": "Test Doc",
7    "split_code": "SPL_UO2vBzEqHW",
8    "integration": 428626,
9    "domain": "test",
10    "type": "percentage",
11    "active": 1,
12    "currency": "NGN",
13    "bearer_type": "subaccount",
14    "bearer_subaccount": 40809,
15    "created_at": "2020-06-30T11:52:24.000Z",
16    "updated_at": "2020-06-30T11:52:24.000Z",
17    "subaccounts": [
18      {
19        "subaccount": {
20          "id": 40809,
21          "subaccount_code": "ACCT_z3x6z3nbo14xsil",
22          "business_name": "Business Name",
23          "description": "Business Description",
24          "primary_contact_name": null,
25          "primary_contact_email": null,
26          "primary_contact_phone": null,
27          "metadata": null,
28          "percentage_charge": 80,
29          "settlement_bank": "Business Bank",
30          "account_number": "1234567890"
31        },
32        "share": 30
33      },
34      {
35        "subaccount": {
36          "id": 40811,
37          "subaccount_code": "ACCT_pwwualwty4nhq9d",
38          "business_name": "Business Name",
39          "description": "Business Description",
40          "primary_contact_name": null,
41          "primary_contact_email": null,
42          "primary_contact_phone": null,
43          "metadata": null,
44          "percentage_charge": 80,
45          "settlement_bank": "Business Bank",
46          "account_number": "0123456789"
47        },
48        "share": 20
49      }
50    ],
51    "total_subaccounts": 2
52  }
53}

Update Split

Update a transaction split details on your integration

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

Path Parameters
id String	Split ID

Body Parameters
Show optional parameters
name String	Name of the transaction split
active Boolean	True or False
bearer_type String	Any of the following values: subaccount \| account \| all-proportional \| all
bearer_subaccount String	Subaccount code of a subaccount in the split group. This should be specified only if the `bearer_type` is `subaccount`

1#!/bin/sh
2url="https://api.paystack.co/split/{id}"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6  "name": "Newness", 
7  "active": true
8}'
9
10curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X PUT

1{
2  "status": true,
3  "message": "Split group updated",
4  "data": {
5    "id": 95,
6    "name": "Updated Name",
7    "type": "percentage",
8    "currency": "NGN",
9    "integration": 165956,
10    "domain": "test",
11    "split_code": "SPL_uMzcGbG5ca",
12    "active": false,
13    "bearer_type": "all",
14    "bearer_subaccount": null,
15    "createdAt": "2020-06-22T16:20:53.000Z",
16    "updatedAt": "2020-06-22T17:26:59.000Z",
17    "subaccounts": [
18      {
19        "subaccount": {
20          "id": 12700,
21          "subaccount_code": "ACCT_jsuq5uwf3n8la7b",
22          "business_name": "Ayobami GTB",
23          "description": "Ayobami GTB",
24          "primary_contact_name": null,
25          "primary_contact_email": null,
26          "primary_contact_phone": null,
27          "metadata": null,
28          "percentage_charge": 20,
29          "settlement_bank": "Guaranty Trust Bank",
30          "account_number": "0259111351"
31        },
32        "share": 80
33      }
34    ],
35    "total_subaccounts": 1
36  }
37}

Add/Update Subaccount Split

Add a Subaccount to a Transaction Split, or update the share of an existing Subaccount in a Transaction Split

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

Path Parameters
id String	Split Id

Body Parameters
subaccount String	This is the sub account code
share Integer	This is the transaction share for the subaccount

1#!/bin/sh
2url="https://api.paystack.co/split/:id/subaccount/add"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6  "subaccount": "ACCT_hdl8abxl8drhrl3", 
7  "share": 40000
8}'
9
10curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST

1{
2  "status": true,
3  "message": "Subaccount added",
4  "data": {
5    "id": 143,
6    "name": "Test Doc",
7    "type": "percentage",
8    "currency": "NGN",
9    "integration": 428626,
10    "domain": "test",
11    "split_code": "SPL_UO2vBzEqHW",
12    "active": true,
13    "bearer_type": "subaccount",
14    "bearer_subaccount": 40809,
15    "createdAt": "2020-06-30T11:52:24.000Z",
16    "updatedAt": "2020-06-30T11:52:24.000Z",
17    "subaccounts": [
18      {
19        "subaccount": {
20          "id": 40809,
21          "subaccount_code": "ACCT_sv6roe394nkpu6j",
22          "business_name": "Business Name",
23          "description": "Business Description",
24          "primary_contact_name": null,
25          "primary_contact_email": null,
26          "primary_contact_phone": null,
27          "metadata": null,
28          "percentage_charge": 20,
29          "settlement_bank": "Business Bank",
30          "account_number": "1234567890"
31        },
32        "share": 30
33      },
34      {
35        "subaccount": {
36          "id": 40811,
37          "subaccount_code": "ACCT_7i76qpjh7rr6q3z",
38          "business_name": "Business Name",
39          "description": "Business Description",
40          "primary_contact_name": null,
41          "primary_contact_email": null,
42          "primary_contact_phone": null,
43          "metadata": null,
44          "percentage_charge": 20,
45          "settlement_bank": "Business Bank",
46          "account_number": "0123456789"
47        },
48        "share": 30
49      }
50    ],
51    "total_subaccounts": 2
52  }
53}

Remove Subaccount from Split

Remove a subaccount from a transaction split

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

Path Parameters
id String	Split Id

Body Parameters
subaccount String	This is the sub account code

1#!/bin/sh
2url="https://api.paystack.co/split/:id/subaccount/remove"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6  "subaccount": "ACCT_hdl8abxl8drhrl3"
7}'
8
9curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST

1{
2  "status": true,
3  "message": "Subaccount removed"
4}