Sign in

Payments

Split a payment with a subaccount

View as Markdown

In a nutshell

Pass a subaccount code when you initialize a payment to split it with one partner by percentage or fixed amount.

Pass a subaccount code when you initialize a payment to split it with one partner. Paystack settles your share to your main account and the partner's share to the subaccount.

Before you start, create a subaccount for the partner and save its subaccount_code. To divide one payment between several partners, split it across multiple subaccounts instead.

Copy linkCollect a payment with the subaccount

Add subaccount to your Initialize Transaction request. Paystack splits the payment by the subaccount's percentage_charge.

POSTapi.paystack.co/transaction/initialize

curl https://api.paystack.co/transaction/initialize \
  -H "Authorization: Bearer $PAYSTACK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "amount": 2000000,
    "subaccount": "ACCT_6uujpqtzmnufzkw"
  }' \
  -X POST
const https = require("https");

const params = JSON.stringify({
  "email": "[email protected]",
  "amount": 2000000,
  "subaccount": "ACCT_6uujpqtzmnufzkw"
});

const options = {
  hostname: "api.paystack.co",
  port: 443,
  path: "/transaction/initialize",
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAYSTACK_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
};

const req = https.request(options, (res) => {
  let data = "";
  res.on("data", (chunk) => {
    data += chunk;
  });
  res.on("end", () => {
    console.log(res.statusCode, JSON.parse(data));
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.write(params);
req.end();
<?php
$fields = [
  "email" => "[email protected]",
  "amount" => 2000000,
  "subaccount" => "ACCT_6uujpqtzmnufzkw",
];

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.paystack.co/transaction/initialize",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode($fields),
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer " . getenv("PAYSTACK_SECRET_KEY"),
    "Content-Type: application/json",
    "Cache-Control: no-cache",
  ),
));
$response = curl_exec($curl);
echo curl_getinfo($curl, CURLINFO_HTTP_CODE) . " " . $response;
?>
{
  "status": true,
  "message": "Authorization URL created",
  "data": {
    "authorization_url": "https://checkout.paystack.com/0peioxfhpn7ghr1",
    "access_code": "0peioxfhpn7ghr1",
    "reference": "s8h3qm1vzc"
  }
}

Send the customer to the authorization_url, or open checkout with the access_code. Paystack applies the split when the payment succeeds.

Amounts are in the currency's subunit (cents), so 2000000 is ZAR 20,000. On this 2000000 payment, with percentage_charge: 20:

  • Oasis Foods gets 1600000.
  • Your main account gets 400000 and pays the Paystack fee from it.

Copy linkKeep a fixed amount instead of a percentage

To keep a fixed amount in your main account, pass transaction_charge in the currency's subunit. It overrides percentage_charge for this payment only. Here your main account gets 300000 and Oasis Foods gets the rest:

POSTapi.paystack.co/transaction/initialize

curl https://api.paystack.co/transaction/initialize \
  -H "Authorization: Bearer $PAYSTACK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "amount": 2000000,
    "subaccount": "ACCT_6uujpqtzmnufzkw",
    "transaction_charge": 300000
  }' \
  -X POST
const https = require("https");

const params = JSON.stringify({
  "email": "[email protected]",
  "amount": 2000000,
  "subaccount": "ACCT_6uujpqtzmnufzkw",
  "transaction_charge": 300000
});

const options = {
  hostname: "api.paystack.co",
  port: 443,
  path: "/transaction/initialize",
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAYSTACK_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
};

const req = https.request(options, (res) => {
  let data = "";
  res.on("data", (chunk) => {
    data += chunk;
  });
  res.on("end", () => {
    console.log(res.statusCode, JSON.parse(data));
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.write(params);
req.end();
<?php
$fields = [
  "email" => "[email protected]",
  "amount" => 2000000,
  "subaccount" => "ACCT_6uujpqtzmnufzkw",
  "transaction_charge" => 300000,
];

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.paystack.co/transaction/initialize",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode($fields),
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer " . getenv("PAYSTACK_SECRET_KEY"),
    "Content-Type: application/json",
    "Cache-Control: no-cache",
  ),
));
$response = curl_exec($curl);
echo curl_getinfo($curl, CURLINFO_HTTP_CODE) . " " . $response;
?>
{
  "status": true,
  "message": "Authorization URL created",
  "data": {
    "authorization_url": "https://checkout.paystack.com/8w3hdrq5vkc1zpe",
    "access_code": "8w3hdrq5vkc1zpe",
    "reference": "t7k2mzq9xa"
  }
}

Copy linkChoose who pays the Paystack fee

To make the subaccount pay the Paystack fee, pass bearer: "subaccount". Otherwise your main account pays it.

POSTapi.paystack.co/transaction/initialize

curl https://api.paystack.co/transaction/initialize \
  -H "Authorization: Bearer $PAYSTACK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "amount": 2000000,
    "subaccount": "ACCT_6uujpqtzmnufzkw",
    "bearer": "subaccount"
  }' \
  -X POST
const https = require("https");

const params = JSON.stringify({
  "email": "[email protected]",
  "amount": 2000000,
  "subaccount": "ACCT_6uujpqtzmnufzkw",
  "bearer": "subaccount"
});

const options = {
  hostname: "api.paystack.co",
  port: 443,
  path: "/transaction/initialize",
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAYSTACK_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
};

const req = https.request(options, (res) => {
  let data = "";
  res.on("data", (chunk) => {
    data += chunk;
  });
  res.on("end", () => {
    console.log(res.statusCode, JSON.parse(data));
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.write(params);
req.end();
<?php
$fields = [
  "email" => "[email protected]",
  "amount" => 2000000,
  "subaccount" => "ACCT_6uujpqtzmnufzkw",
  "bearer" => "subaccount",
];

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.paystack.co/transaction/initialize",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode($fields),
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer " . getenv("PAYSTACK_SECRET_KEY"),
    "Content-Type: application/json",
    "Cache-Control: no-cache",
  ),
));
$response = curl_exec($curl);
echo curl_getinfo($curl, CURLINFO_HTTP_CODE) . " " . $response;
?>
{
  "status": true,
  "message": "Authorization URL created",
  "data": {
    "authorization_url": "https://checkout.paystack.com/k1v9tq7ymz3rdo2",
    "access_code": "k1v9tq7ymz3rdo2",
    "reference": "b4xw8lnq2e"
  }
}

The subaccount's share must cover the fee

Use bearer: "subaccount" only when the subaccount's share is larger than the Paystack fee. Otherwise, Initialize Transaction returns 400 Bad Request.

Copy linkSplit Popup and saved-card payments

Use the equivalent fields to split a payment from Paystack Popup or Charge Authorization:

  • Paystack Popup: pass subaccountCode, transactionCharge, and bearer. See Split transaction.
  • Charge Authorization: pass subaccount, transaction_charge, and bearer to Charge Authorization to split a repeat payment from a saved card.

Copy linkConfirm the split

Use the charge.success webhook as your primary signal to fulfill orders, grant access, or update your database. The customer can close the page before your callback runs, but the webhook still arrives.

Add your webhook URL on the Paystack Dashboard, and verify the signature on every event with your webhook signing secret.

To see each party's share, verify the payment with its reference. In fees_split, each share is in the currency's subunit and integration is your main account. This response, trimmed to the split fields, is for the first 2000000 payment on this page:

{
  "status": true,
  "message": "Verification successful",
  "data": {
    "id": 696105911,
    "status": "success",
    "reference": "s8h3qm1vzc",
    "amount": 2000000,
    "currency": "ZAR",
    "fees": 58100,
    "fees_split": {
      "paystack": 58100,
      "integration": 341900,
      "subaccount": 1600000
    },
    "subaccount": {
      "subaccount_code": "ACCT_6uujpqtzmnufzkw",
      "business_name": "Oasis Foods",
      "percentage_charge": 20
    }
  }
}

The fee in this example uses standard pricing for ZAR local card payments. Your fee depends on your pricing and the payment channel.

Was this page helpful?