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)`
);
}
}
