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 "main_account_share":100
18 }'
19-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 are fractional monetary units (kobo, cents, pesewas, etc)
  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: "[email protected]", amount: "20000",
5 split_code: "SPL_98WF13Eekw" }'
6-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: "[email protected]",
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": "[email protected]",
38 "customer_code": "CUS_wt0zmhzb0xqd4nr",
39 "phone": null,
40 "metadata": null,
41 "risk_action": "default"
42 },
43 "plan": null,
44 "id": 696105928
45 }
46}

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 ...
13 "split": {
14 "id": 10,
15 "name": "Example Split",
16 "split_code": "SPL_98WF13Eekw",
17 "formula": {
18 "type": "percentage",
19 "subaccounts": [
20 {
21 "share": 20,
22 "subaccount_code": "ACCT_zpu16k4uhxycmxu",
23 "id": 12850,
24 "name": "Ayobami UBA"
25 }
26 ],
27 "integration": 80
28 },
29 "shares": {
30 "paystack": 140,
31 "subaccounts": [
32 {
33 "amount": 2000,
34 "subaccount_code": "ACCT_zpu16k4uhxycmxu",
35 "id": 12850
36 }
37 ],
38 "integration": 7860
39 }
40 },
41 ...
42 }
43}