Paystack Settlements

The Settlements API lets you track payouts from Paystack to your bank account.

Depends on: paystack-setup for the paystackRequest helper.

Endpoints

Method	Endpoint	Description
GET	/settlement	List settlements
GET	/settlement/:id/transactions	List transactions in a settlement

Settlement Statuses

Status	Description
success	Funds successfully deposited
processing	Settlement is being processed
pending	Settlement is queued
failed	Settlement failed

List Settlements

Param	Type	Required	Description
perPage	integer	No	Records per page (default: 50)
page	integer	No	Page number (default: 1)
status	string	No	success, processing, pending, or failed
subaccount	string	No	Subaccount ID, or none for main account only
from	datetime	No	Start date
to	datetime	No	End date

// All successful settlements
const settlements = await paystackRequest(
  "/settlement?status=success&from=2024-01-01&to=2024-01-31"
);

// settlements.data[0]:
// {
//   id: 3090024,
//   status: "success",
//   currency: "NGN",
//   total_amount: 995,       // Amount settled (subunits)
//   effective_amount: 995,   // Amount after deductions
//   total_fees: 5,           // Paystack fees
//   total_processed: 1000,   // Gross transaction amount
//   settlement_date: "2022-11-09T00:00:00.000Z"
// }

// Main account settlements only (exclude subaccounts)
await paystackRequest("/settlement?subaccount=none");

// Specific subaccount settlements
await paystackRequest("/settlement?subaccount=ACCT_6uujpqtzmnufzkw");

List Settlement Transactions

Get the individual transactions that make up a settlement:

const txs = await paystackRequest(
  `/settlement/${settlementId}/transactions?perPage=50&page=1`
);

// txs.data[0]:
// {
//   id: 2067030515,       // Store as unsigned 64-bit integer
//   status: "success",
//   reference: "da8ed5u8sz6yn95",
//   amount: 10000,
//   channel: "card",
//   currency: "NGN",
//   paid_at: "2022-09-01T10:36:37.000Z"
// }

Important: Transaction IDs should be stored as unsigned 64-bit integers.

Reconciliation Pattern

async function reconcileSettlements(from: string, to: string) {
  const settlements = await paystackRequest(
    `/settlement?status=success&from=${from}&to=${to}`
  );

  for (const settlement of settlements.data) {
    const txs = await paystackRequest(
      `/settlement/${settlement.id}/transactions`
    );

    console.log(
      `Settlement #${settlement.id}: ` +
      `₦${(settlement.total_processed / 100).toFixed(2)} gross → ` +
      `₦${(settlement.effective_amount / 100).toFixed(2)} net ` +
      `(${txs.data.length} transactions)`
    );
  }
}