Split Payments

In A Nutshell
In a nutshell

With split payments you can share your settlement for a transaction with another account

Implementing split payments involves:

  1. Create a subaccount
  2. Initialize a split payment

Create a subaccount

Subaccounts can be created via the Paystack Dashboard or using the create subaccountAPI endpoint. When a subaccount is created, the subaccount_code is returned.

Show Response
1curl https://api.paystack.co/subaccount
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "business_name": "Cheese Sticks",
5 "bank_code": "058",
6 "account_number": "0123456789",
7 "percentage_charge": 0.2
8 }'
9-X POST
1{
2 "status": true,
3 "message": "Subaccount created",
4 "data": {
5 "business_name": "Cheese Sticks",
6 "account_number": "0123456789",
7 "percentage_charge": 0.2,
8 "settlement_bank": "Guaranty Trust Bank",
9 "integration": 428626,
10 "domain": "test",
11 "subaccount_code": "ACCT_xxxxxxxxxxxxx",
12 "is_verified": false,
13 "settlement_schedule": "AUTO",
14 "active": true,
15 "migrate": false,
16 "id": 37614,
17 "createdAt": "2020-05-19T11:54:20.655Z",
18 "updatedAt": "2020-05-19T11:54:20.655Z"
19 }
20}
Verify Account Number

Please endeavour to verify that the bank account details matches what you intended. Paystack will not be liable for payouts to the wrong bank account.

Initialize a split payment

Split payments can be initialized by using the Initialize TransactionAPI endpoint and passing the parameter subaccount: "SUB_ACCOUNTCODE".

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 "subaccount": "ACCT_xxxxxxxxx"
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}

Split payments can be used in the following scenario:

  • Shared payment between service provider and platform provider
  • Split profit between different vendors
  • Separate school fees in different account e.g. Tuition, Accomodation, Excursion

Flat Fee

By default, payments are split by percentage. For example, if a subaccount was created with percentage_charge: 0.2, 20% goes to the subaccount and the rest goes to the main account.

However, you can override this default and specify a flat fee that goes into your main account. To do this, pass the transaction_charge key when intializing a transaction.

In the snippet below, the main account gets a flat fee of 10000 and the subaccount gets the rest:

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 "subaccount": "ACCT_xxxxxxxxx",
7 "transaction_charge": 10000
8 }'
9-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}

Bearer of Transaction Fee

By default, the Paystack charges are borne by the main account. To change this to a subaccount, pass the param bearer: "subaccount" while intializing a transaction.

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 "subaccount": "ACCT_xxxxxxxxx",
7 "bearer": "subaccount"
8 }'
9-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}
Invalid Split Configuration

When specifying a bearer, you need to ensure that the amount that goes into the subaccount is sufficient to bear the transaction fee. If the amount is insufficient, you'll get a 400 Bad Request error.