Multi-split Payments

In A Nutshell
In a nutshell

Multi-split enables merchants to split the settlement for a transaction across their payout account, and one or more subaccounts.

You can implement multi-split by:

  1. Creating a transaction split
  2. Using transaction splits with payments

Merchants will be able to create and manage their transaction splits using the Transaction SplitsAPI endpoints and their Paystack Dashboard.

Creating a transaction split

Before you begin

Transaction split depends on subaccounts to work its magic. If you already have subaccounts, you can proceed. Otherwise, you'll need to create a subaccount first.

You can create a transaction split by sending a request to the Create SplitAPI endpoint with the following information:

  • The type of split (flat or percentage)
  • An array of subaccounts and their respective shares
Show Response
1curl https://api.paystack.co/split
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "name":"Percentage Split",
5 "type":"percentage",
6 "currency": "NGN",
7 "subaccounts":[{
8 "subaccount": "ACCT_z3x6z3nbo14xsil",
9 "share": 20
10 },
11 {
12 "subaccount": "ACCT_pwwualwty4nhq9d",
13 "share": 30
14 }],
15 "bearer_type":"subaccount",
16 "bearer_subaccount":"ACCT_hdl8abxl8drhrl3"
17 }'
18-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}
Warning
  1. We don't accept decimal figures for subaccounts shares if the split type is percentage
  2. The sum of the percentage splits should not be more than 100%
  3. Share amounts for flat splits whic should be in the subunit of the supported currency
  4. The sum of the flat splits should not be more than the transaction amount

Through the APIs, you can add, remove, and update the subaccounts in a Split, as well as change the active state of a Split.

Updating a Split

You can't change the type of a split. Instead, you can deactivate the Split and create a new Split with a different split type.

Using transaction splits with payments

After creating a transaction split, you can make use of it when:

  1. Initializing a transaction
  2. Charging an authorization

Initializing a transaction

You can initialize a transaction with a Transaction Split by adding a split_code to the payload you send to the Transaction InitializeAPI endpoint.

Show Response
1curl https://api.paystack.co/transaction/initialize
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "email": "customer@email.com",
5 "amount": "20000",
6 "split_code": "SPL_98WF13Eekw"
7 }'
8-X POST
1{
2 "status": true,
3 "message": "Authorization URL created",
4 "data": {
5 "authorization_url": "https://checkout.paystack.com/nkdks46nymizns7",
6 "access_code": "nkdks46nymizns7",
7 "reference": "nms6uvr1pl"
8 }
9}

Charging an authorization

To charge an authorization with a Transaction Split, add a split_code to the payload you send to the Charge AuthorizationAPI endpoint.

Show Response
1curl https://api.paystack.co/transaction/charge_authorization
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "authorization_code" : "AUTH_12abc345de", "email": "mail@mail.com",
5 "amount": "300000", "split_code": "SPL_UO2vBzEqHW" }'
6-X POST
1{
2 "status": true,
3 "message": "Charge attempted",
4 "data": {
5 "amount": 300000,
6 "currency": "NGN",
7 "transaction_date": "2020-05-27T11:45:03.000Z",
8 "status": "success",
9 "reference": "cn65lf4ixmkzvda",
10 "domain": "test",
11 "metadata": "",
12 "gateway_response": "Approved",
13 "message": null,
14 "channel": "card",
15 "ip_address": null,
16 "log": null,
17 "fees": 14500,
18 "authorization": {
19 "authorization_code": "AUTH_12abc345de",
20 "bin": "408408",
21 "last4": "4081",
22 "exp_month": "12",
23 "exp_year": "2020",
24 "channel": "card",
25 "card_type": "visa DEBIT",
26 "bank": "Test Bank",
27 "country_code": "NG",
28 "brand": "visa",
29 "reusable": true,
30 "signature": "SIG_2Gvc6pNuzJmj4TCchXfp",
31 "account_name": null
32 },
33 "customer": {
34 "id": 23215815,
35 "first_name": null,
36 "last_name": null,
37 "email": "mail@mail.com",
38 "customer_code": "CUS_wt0zmhzb0xqd4nr",
39 "phone": null,
40 "metadata": null,
41 "risk_action": "default"
42 },
43 "plan": null,
44 "id": 696105928
45 }
46}

Dynamic Splits

Sometimes, you can't determine a split configuration until later in the purchase flow. With dynamic splits, you can create splits on the fly. This can be achieved by passing a split object to the Transaction InitializeAPI endpoint or to popup. The split object can take the following properties:

ParamRequired?Description
typeYesValue can be flat or percentage
bearer_typeYesValue can be all, all-proportional, account or subaccount
subaccountsYesAn array of subaccount object. e.g. {"subaccount": 'ACCT_', "share": 60}
bearer_subaccountNoSubaccount code of the bearer. It should be specified if bearer_type is subaccount
referenceNoUnique reference of the split
Show Response
1curl https://api.paystack.co/transaction/initialize
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "email": "customer@email.com",
5 "amount": "20000",
6 "split": {
7 "type": "flat",
8 "bearer_type": "account",
9 "subaccounts": [
10 {
11 "subaccount": "ACCT_pwwualwty4nhq9d",
12 "share": 6000
13 },
14 {
15 "subaccount": "ACCT_hdl8abxl8drhrl3",
16 "share": 4000
17 },
18 ]
19 }
20}'
21-X POST
1{
2 "status": true,
3 "message": "Authorization URL created",
4 "data": {
5 "authorization_url": "https://checkout.paystack.com/nkdks46nymizns7",
6 "access_code": "nkdks46nymizns7",
7 "reference": "nms6uvr1pl"
8 }
9}

Webhooks

For successful transactions, we'll populate a split parameter in the charge.success webhook with information on the Split:

1{
2 "event": "charge.success",
3 "data": {
4 "id": 697123356,
5 "domain": "live",
6 "status": "success",
7 "reference": "12k81tq3my",
8 "amount": 10000,
9 "message": null,
10 "gateway_response": "Approved",
11 "paid_at": "2020-05-28T13:54:57.000Z",
12 "split": {
13 "id": 10,
14 "name": "Example Split",
15 "split_code": "SPL_98WF13Eekw",
16 "formula": {
17 "type": "percentage",
18 "subaccounts": [
19 {
20 "share": 20,
21 "subaccount_code": "ACCT_zpu16k4uhxycmxu",
22 "id": 12850,
23 "name": "Ayobami UBA"
24 }
25 ],
26 "integration": 80
27 },
28 "shares": {
29 "paystack": 140,
30 "subaccounts": [
31 {
32 "amount": 2000,
33 "subaccount_code": "ACCT_zpu16k4uhxycmxu",
34 "id": 12850
35 }
36 ],
37 "integration": 7860
38 }
39 }
40 }
41}

Fees on Multi-split

By default, the main account bears the Paystack transaction fees. However, you can change this by setting the bearer_type to either account, all or subaccount.

Bearer TypeDescription
all Fees will be shared equally by the main account and all subaccounts.
all-proportional Fees will be charged according to the share of the main account and subaccounts.
account Fees will be charged to the main account only.
subaccount Only the subaccount set in the bearer_subaccount will be charged
Bearer Subaccount

A required parameter when the bearer_type is set to subaccount. The value of bearer_subaccount must be a subaccount code that's in the split group.