Multi-split Payments
In a nutshell
You can implement multi-split by:
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
You can create a transaction split by sending a request to the Create SplitAPI endpoint with the following information:
- The type of split (
flat
orpercentage
) - An array of subaccounts and their respective shares
1curl https://api.paystack.co/split2-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": 2010 },11 {12 "subaccount": "ACCT_pwwualwty4nhq9d",13 "share": 3014 }],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": 2033 },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": 3049 }50 ],51 "total_subaccounts": 252 }53}
Warning
- We don't accept decimal figures for subaccounts shares if the split type is
percentage
- The sum of the
percentage
splits should not be more than 100% - Share amounts for
flat
splits are fractional monetary units (kobo, cents, pesewas, etc) - 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
Using transaction splits with payments
After creating a transaction split, you can make use of it when:
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.
1curl https://api.paystack.co/transaction/initialize2-H "Authorization: Bearer YOUR_SECRET_KEY"3-H "Content-Type: application/json"4-d '{ "email": "customer@email.com", "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.
1curl https://api.paystack.co/transaction/charge_authorization2-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": null32 },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": 69610592845 }46}
Dynamic Splits
Sometimes, you can't determine a split configuration until later in the purchase flow. With dynamic splits, you can create split 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:
Param | Required? | Description |
---|---|---|
type | Yes | Value can be flat or percentage |
bearer_type | Yes | Value can be all , all-proportional , account or subaccount |
subaccounts | Yes | An array of subaccount object. e.g. { "subaccount": 'ACCT_', "share": 60 } |
bearer_subaccount | No | Subaccount code of the bearer. It should be specified if bearer_type is subaccount |
reference | No | Unique reference of the split |
1curl https://api.paystack.co/transaction/initialize2-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": 600013 },14 {15 "subaccount": "ACCT_hdl8abxl8drhrl3",16 "share": 400017 },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:
- JSON
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": 8028 },29 "shares": {30 "paystack": 140,31 "subaccounts": [32 {33 "amount": 2000,34 "subaccount_code": "ACCT_zpu16k4uhxycmxu",35 "id": 1285036 }37 ],38 "integration": 786039 }40 },41 ...42 }43}
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 Type | Description |
---|---|
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
bearer_type
is set to subaccount
. The value of bearer_subaccount
must be a subaccount code that's in the split group.