Settlements

The Settlements API allows you gain insights into payouts made by Paystack to your bank account.

List Settlements

List settlements made to your settlement accounts

Headers
authorization
String
Set value to Bearer SECRET_KEY
Query Parameters
perPage
Integer
Specify how many records you want to retrieve per page. If not specify we use a default value of 50.
page
Integer
Specify exactly what page you want to retrieve. If not specify we use a default value of 1.
status
String
Fetch settlements based on their state. Value can be one of success, processing, pending or failed.
subaccount
String
Provide a subaccount ID to export only settlements for that subaccount. Set to none to export only transactions for the account.
from
Datetime
A timestamp from which to start listing settlements e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
to
Datetime
A timestamp at which to stop listing settlements e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
Show optional parameters
GET/settlement
cURL
1#!/bin/sh
2url="https://api.paystack.co/settlement"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X GET
Sample Response
200 Ok
1{
2 "status": true,
3 "message": "Settlements retrieved",
4 "data": [
5 {
6 "id": 3090024,
7 "domain": "live",
8 "status": "success",
9 "currency": "NGN",
10 "integration": 463433,
11 "total_amount": 995,
12 "effective_amount": 995,
13 "total_fees": 5,
14 "total_processed": 1000,
15 "deductions": null,
16 "settlement_date": "2022-11-09T00:00:00.000Z",
17 "settled_by": null,
18 "createdAt": "2022-11-09T01:04:08.000Z",
19 "updatedAt": "2022-11-09T08:12:01.000Z"
20 },
21 {
22 "id": 2856168,
23 "domain": "live",
24 "status": "success",
25 "currency": "NGN",
26 "integration": 463433,
27 "total_amount": 9610,
28 "effective_amount": 9610,
29 "total_fees": 390,
30 "total_processed": 10000,
31 "deductions": null,
32 "settlement_date": "2022-09-02T00:00:00.000Z",
33 "settled_by": null,
34 "createdAt": "2022-09-02T01:14:11.000Z",
35 "updatedAt": "2022-09-02T04:32:01.000Z"
36 },
37 {
38 "id": 2276794,
39 "domain": "live",
40 "status": "success",
41 "currency": "NGN",
42 "integration": 463433,
43 "total_amount": 4975,
44 "effective_amount": 4975,
45 "total_fees": 25,
46 "total_processed": 5000,
47 "deductions": null,
48 "settlement_date": "2022-02-26T00:00:00.000Z",
49 "settled_by": null,
50 "createdAt": "2022-02-26T01:24:27.000Z",
51 "updatedAt": "2022-02-28T09:32:00.000Z"
52 },
53 {
54 "id": 2255771,
55 "domain": "live",
56 "status": "success",
57 "currency": "NGN",
58 "integration": 463433,
59 "total_amount": 38356,
60 "effective_amount": 38356,
61 "total_fees": 194,
62 "total_processed": 38550,
63 "deductions": null,
64 "settlement_date": "2022-02-19T00:00:00.000Z",
65 "settled_by": null,
66 "createdAt": "2022-02-19T01:23:31.000Z",
67 "updatedAt": "2022-02-21T09:32:00.000Z"
68 },
69 {
70 "id": 2246373,
71 "domain": "live",
72 "status": "success",
73 "currency": "NGN",
74 "integration": 463433,
75 "total_amount": 24875,
76 "effective_amount": 24875,
77 "total_fees": 125,
78 "total_processed": 25000,
79 "deductions": null,
80 "settlement_date": "2022-02-16T00:00:00.000Z",
81 "settled_by": null,
82 "createdAt": "2022-02-16T01:24:09.000Z",
83 "updatedAt": "2022-02-16T09:12:00.000Z"
84 },
85 {
86 "id": 2234251,
87 "domain": "live",
88 "status": "success",
89 "currency": "NGN",
90 "integration": 463433,
91 "total_amount": 0,
92 "effective_amount": 0,
93 "total_fees": 1,
94 "total_processed": 1,
95 "deductions": null,
96 "settlement_date": "2022-02-12T00:00:00.000Z",
97 "settled_by": null,
98 "createdAt": "2022-02-12T01:20:50.000Z",
99 "updatedAt": "2022-02-14T06:07:07.000Z"
100 },
101 {
102 "id": 2046406,
103 "domain": "live",
104 "status": "success",
105 "currency": "NGN",
106 "integration": 463433,
107 "total_amount": 15439,
108 "effective_amount": 15439,
109 "total_fees": 78,
110 "total_processed": 15517,
111 "deductions": null,
112 "settlement_date": "2021-12-07T00:00:00.000Z",
113 "settled_by": null,
114 "createdAt": "2021-12-07T01:25:18.000Z",
115 "updatedAt": "2021-12-07T09:42:03.000Z"
116 },
117 {
118 "id": 1986550,
119 "domain": "live",
120 "status": "pending",
121 "currency": "NGN",
122 "integration": 463433,
123 "total_amount": 4975,
124 "effective_amount": 4975,
125 "total_fees": 25,
126 "total_processed": 5000,
127 "deductions": null,
128 "settlement_date": "2021-11-16T00:00:00.000Z",
129 "settled_by": null,
130 "createdAt": "2021-11-16T01:17:49.000Z",
131 "updatedAt": "2021-11-16T01:17:49.000Z"
132 },
133 {
134 "id": 1955844,
135 "domain": "live",
136 "status": "success",
137 "currency": "NGN",
138 "integration": 463433,
139 "total_amount": 29550,
140 "effective_amount": 29550,
141 "total_fees": 450,
142 "total_processed": 30000,
143 "deductions": null,
144 "settlement_date": "2021-11-05T00:00:00.000Z",
145 "settled_by": null,
146 "createdAt": "2021-11-05T01:14:28.000Z",
147 "updatedAt": "2021-11-09T08:42:09.000Z"
148 },
149 {
150 "id": 1913601,
151 "domain": "live",
152 "status": "pending",
153 "currency": "NGN",
154 "integration": 463433,
155 "total_amount": 9850,
156 "effective_amount": 9850,
157 "total_fees": 150,
158 "total_processed": 10000,
159 "deductions": null,
160 "settlement_date": "2021-10-21T00:00:00.000Z",
161 "settled_by": null,
162 "createdAt": "2021-10-21T01:05:22.000Z",
163 "updatedAt": "2021-10-21T01:05:22.000Z"
164 },
165 {
166 "id": 1897850,
167 "domain": "live",
168 "status": "success",
169 "currency": "NGN",
170 "integration": 463433,
171 "total_amount": 6965,
172 "effective_amount": 6965,
173 "total_fees": 35,
174 "total_processed": 7000,
175 "deductions": null,
176 "settlement_date": "2021-10-15T00:00:00.000Z",
177 "settled_by": null,
178 "createdAt": "2021-10-15T01:03:17.000Z",
179 "updatedAt": "2021-10-15T15:07:39.000Z"
180 },
181 {
182 "id": 1875499,
183 "domain": "live",
184 "status": "success",
185 "currency": "NGN",
186 "integration": 463433,
187 "total_amount": 33635,
188 "effective_amount": 33635,
189 "total_fees": 1365,
190 "total_processed": 35000,
191 "deductions": null,
192 "settlement_date": "2021-10-06T00:00:00.000Z",
193 "settled_by": null,
194 "createdAt": "2021-10-06T01:21:08.000Z",
195 "updatedAt": "2021-10-06T10:35:10.000Z"
196 },
197 {
198 "id": 1856831,
199 "domain": "live",
200 "status": "success",
201 "currency": "NGN",
202 "integration": 463433,
203 "total_amount": 9610,
204 "effective_amount": 9610,
205 "total_fees": 390,
206 "total_processed": 10000,
207 "deductions": null,
208 "settlement_date": "2021-09-29T00:00:00.000Z",
209 "settled_by": null,
210 "createdAt": "2021-09-29T01:17:33.000Z",
211 "updatedAt": "2021-10-15T15:07:38.000Z"
212 },
213 {
214 "id": 1319048,
215 "domain": "live",
216 "status": "success",
217 "currency": "NGN",
218 "integration": 463433,
219 "total_amount": 4925,
220 "effective_amount": 4925,
221 "total_fees": 75,
222 "total_processed": 5000,
223 "deductions": null,
224 "settlement_date": "2021-02-10T00:00:00.000Z",
225 "settled_by": null,
226 "createdAt": "2021-02-10T01:03:25.000Z",
227 "updatedAt": "2021-06-22T17:00:36.000Z"
228 },
229 {
230 "id": 1060807,
231 "domain": "live",
232 "status": "success",
233 "currency": "NGN",
234 "integration": 463433,
235 "total_amount": 19700,
236 "effective_amount": 19700,
237 "total_fees": 300,
238 "total_processed": 20000,
239 "deductions": null,
240 "settlement_date": "2020-09-30T00:00:00.000Z",
241 "settled_by": null,
242 "createdAt": "2020-09-30T01:12:49.000Z",
243 "updatedAt": "2020-09-30T09:23:02.000Z"
244 }
245 ],
246 "meta": {
247 "total": 15,
248 "skipped": 0,
249 "perPage": 50,
250 "page": 1,
251 "pageCount": 1
252 }
253}

List Settlement Transactions

Get the transactions that make up a particular settlement

Transaction ID data type

If you plan to store or make use of the the transaction ID, you should represent it as a unsigned 64-bit integer. To learn more, check out our changelog.

Headers
authorization
String
Set value to Bearer SECRET_KEY
Path Parameters
id
String
The settlement ID in which you want to fetch its transactions
Query Parameters
perPage
Integer
Specify how many records you want to retrieve per page. If not specify we use a default value of 50.
page
Integer
Specify exactly what page you want to retrieve. If not specify we use a default value of 1.
from
Datetime
A timestamp from which to start listing settlement transactions e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
to
Datetime
A timestamp at which to stop listing settlement transactions e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
Show optional parameters
GET/settlement/:id/transactions
cURL
1#!/bin/sh
2url="https://api.paystack.co/settlement/:id/transactions"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X GET
Sample Response
200 Ok
1{
2 "status": true,
3 "message": "Transactions retrieved",
4 "data": [
5 {
6 "id": 2067030515,
7 "domain": "live",
8 "status": "success",
9 "reference": "da8ed5u8sz6yn95",
10 "amount": 10000,
11 "message": "",
12 "gateway_response": "Approved",
13 "paid_at": "2022-09-01T10:36:37.000Z",
14 "created_at": "2022-09-01T10:26:02.000Z",
15 "channel": "card",
16 "currency": "NGN",
17 "ip_address": "172.31.63.124",
18 "metadata": {
19 "custom_fields": [
20 {
21 "value": "makurdi",
22 "display_name": "Donation for",
23 "variable_name": "donation_for"
24 }
25 ]
26 },
27 "log": null,
28 "fees": 390,
29 "fees_split": null,
30 "customer": {
31 "id": 44100000,
32 "first_name": null,
33 "last_name": null,
34 "email": "[email protected]",
35 "phone": null,
36 "metadata": null,
37 "customer_code": "CUS_38uvy1ksasyupp",
38 "risk_action": "default"
39 },
40 "authorization": {
41 "authorization_code": "AUTH_whyjj12345",
42 "bin": "460000",
43 "last4": "1234",
44 "exp_month": "11",
45 "exp_year": "2022",
46 "channel": "card",
47 "card_type": "visa debit",
48 "bank": "",
49 "country_code": "KE",
50 "brand": "visa",
51 "reusable": true,
52 "signature": "SIG_0Rof76ERZlJMnXm9090",
53 "account_name": null
54 },
55 "plan": {},
56 "split": {},
57 "subaccount": {},
58 "order_id": null,
59 "paidAt": "2022-09-01T10:36:37.000Z",
60 "createdAt": "2022-09-01T10:26:02.000Z",
61 "requested_amount": 10000,
62 "source": {
63 "source": "merchant_api",
64 "type": "api",
65 "identifier": null,
66 "entry_point": "transaction_initialize"
67 },
68 "pos_transaction_data": null
69 }
70 ],
71 "meta": {
72 "total": 1,
73 "total_volume": 100,
74 "skipped": 0,
75 "perPage": 50,
76 "page": 1,
77 "pageCount": 1
78 }
79}