List Payouts
The ListPayouts
endpoint provides a list of payouts for a location. If you do not specify a location, the main or default location is used. To call this endpoint, set PAYOUTS_READ
for the OAuth scope.
You can filter payouts by location ID, status, and time range and sort them in ascending or descending order.
The ListPayouts
endpoint supports pagination and a limit field that your application can use to indicate the page size (the number of items to return in the response). The default and maximum page size is 100 items. For more information, see Pagination.
1
2
3
4
curl https://connect.squareupsandbox.com/v2/payouts \
-H 'Square-Version: 2023-03-15' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json'
The following is an example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
{
"payouts": [
{
"id": "po_d001cb2c-82cd-11ec-b8a4-02420a140004",
"status": "SENT",
"location_id": "{LOCATION_ID}",
"created_at": "2022-01-31T19:41:41Z",
"updated_at": "2022-01-31T19:41:41Z",
"amount_money": {
"amount": -88,
"currency_code": "EUR"
},
"destination": {
"type": "BANK_ACCOUNT",
"id": "bact:cgvL1yv43VFjexample"
},
"version": 1,
"type": "BATCH",
"arrival_date": "2022-02-02"
},
{
"id": "po_989fdac5-7fa9-11ec-b8a4-02420a140004",
"status": "SENT",
"location_id": "{LOCATION_ID}",
"created_at": "2022-01-27T19:44:53Z",
"updated_at": "2022-01-27T19:44:53Z",
"amount_money": {
"amount": 3997,
"currency_code": "EUR"
},
"destination": {
"type": "BANK_ACCOUNT",
"id": "bact:cgvL1yv43VFjexample"
},
"version": 1,
"type": "BATCH",
"arrival_date": "2022-01-28"
},
{
"id": "po_eb4dd46f-29f9-11ec-aaa1-02420a140004",
"status": "SENT",
"location_id": "{LOCATION_ID}",
"created_at": "2021-10-10T18:43:11Z",
"updated_at": "2021-10-10T18:43:11Z",
"amount_money": {
"amount": 229,
"currency_code": "EUR"
},
"destination": {
"type": "BANK_ACCOUNT",
"id": "bact:cgvL1yv43VFjexample"
},
"version": 1,
"type": "BATCH"
},
{
"id": "po_3cd4afed-f878-11eb-a8bb-02420a140009",
"status": "SENT",
"location_id": "{LOCATION_ID}",
"created_at": "2021-08-08T18:41:27Z",
"updated_at": "2021-08-08T18:41:27Z",
"amount_money": {
"amount": 26,
"currency_code": "EUR"
},
"destination": {
"type": "BANK_ACCOUNT",
"id": "bact:cgvL1yv43VFjexample"
},
"version": 1,
"type": "BATCH"
},
{
"id": "po_dd5909a2-ee44-11eb-a8bb-02420a140009",
"status": "SENT",
"location_id": "{LOCATION_ID}",
"created_at": "2021-07-26T19:08:30Z",
"updated_at": "2021-07-26T19:08:30Z",
"amount_money": {
"amount": 239,
"currency_code": "EUR"
},
"destination": {
"type": "BANK_ACCOUNT",
"id": "bact:cgvL1yv43VFjexample"
},
"version": 1,
"type": "BATCH"
},
{
"id": "po_dd590570-ee44-11eb-a8bb-02420a140009",
"status": "SENT",
"location_id": "{LOCATION_ID}",
"created_at": "2021-07-26T19:08:30Z",
"updated_at": "2021-07-26T19:08:30Z",
"amount_money": {
"amount": 91,
"currency_code": "EUR"
},
"destination": {
"type": "BANK_ACCOUNT",
"id": "bact:cgvL1yv43VFjexample"
},
"version": 1,
"type": "BATCH"
},
{
"id": "po_070431e4-e351-11eb-a8bb-02420a140009",
"status": "SENT",
"location_id": "{LOCATION_ID}",
"created_at": "2021-07-12T20:37:51Z",
"updated_at": "2022-03-27T20:37:51Z",
"amount_money": {
"amount": 457,
"currency_code": "EUR"
},
"destination": {
"type": "BANK_ACCOUNT",
"id": "bact:cgvL1yv43VFjexample"
},
"version": 1,
"type": "BATCH",
"arrival_date": "2021-07-13"
}
]
}
To see payouts for a specific location, specify the location ID:
1
2
3
4
curl https://connect.squareupsandbox.com/v2/payouts?location_id={{LOCATION_ID}} \
-H 'Square-Version: 2023-03-15' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json'
The following is an example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
{
"payouts": [
{
"id": "po_d001cb2c-82cd-11ec-b8a4-02420a140004",
"status": "SENT",
"location_id": "{LOCATION_ID}",
"created_at": "2022-01-31T19:41:41Z",
"updated_at": "2022-01-31T19:41:41Z",
"amount_money": {
"amount": -88,
"currency_code": "EUR"
},
"destination": {
"type": "BANK_ACCOUNT",
"id": "bact:cgvL1yv43VFjexample"
},
"version": 1,
"type": "BATCH",
"arrival_date": "2022-02-02"
},
{
"id": "po_989fdac5-7fa9-11ec-b8a4-02420a140004",
"status": "SENT",
"location_id": "{LOCATION_ID}",
"created_at": "2022-01-27T19:44:53Z",
"updated_at": "2022-01-27T19:44:53Z",
"amount_money": {
"amount": 3997,
"currency_code": "EUR"
},
"destination": {
"type": "BANK_ACCOUNT",
"id": "bact:cgvL1yv43VFjexample"
},
"version": 1,
"type": "BATCH",
"arrival_date": "2022-01-28"
},
{
"id": "po_eb4dd46f-29f9-11ec-aaa1-02420a140004",
"status": "SENT",
"location_id": "{LOCATION_ID}",
"created_at": "2021-10-10T18:43:11Z",
"updated_at": "2021-10-10T18:43:11Z",
"amount_money": {
"amount": 229,
"currency_code": "EUR"
},
"destination": {
"type": "BANK_ACCOUNT",
"id": "bact:cgvL1yv43VFjexample"
},
"version": 1,
"type": "BATCH"
},
{
"id": "po_3cd4afed-f878-11eb-a8bb-02420a140009",
"status": "SENT",
"location_id": "{LOCATION_ID}",
"created_at": "2021-08-08T18:41:27Z",
"updated_at": "2021-08-08T18:41:27Z",
"amount_money": {
"amount": 26,
"currency_code": "EUR"
},
"destination": {
"type": "BANK_ACCOUNT",
"id": "bact:cgvL1yv43VFjexample"
},
"version": 1,
"type": "BATCH"
},
{
"id": "po_dd5909a2-ee44-11eb-a8bb-02420a140009",
"status": "SENT",
"location_id": "{LOCATION_ID}",
"created_at": "2021-07-26T19:08:30Z",
"updated_at": "2021-07-26T19:08:30Z",
"amount_money": {
"amount": 239,
"currency_code": "EUR"
},
"destination": {
"type": "BANK_ACCOUNT",
"id": "bact:cgvL1yv43VFjexample"
},
"version": 1,
"type": "BATCH"
},
{
"id": "po_dd590570-ee44-11eb-a8bb-02420a140009",
"status": "SENT",
"location_id": "{LOCATION_ID}",
"created_at": "2021-07-26T19:08:30Z",
"updated_at": "2021-07-26T19:08:30Z",
"amount_money": {
"amount": 91,
"currency_code": "EUR"
},
"destination": {
"type": "BANK_ACCOUNT",
"id": "bact:cgvL1yv43VFjexample"
},
"version": 1,
"type": "BATCH"
},
{
"id": "po_070431e4-e351-11eb-a8bb-02420a140009",
"status": "SENT",
"location_id": "{LOCATION_ID}",
"created_at": "2021-07-12T20:37:51Z",
"updated_at": "2022-03-27T20:37:51Z",
"amount_money": {
"amount": 457,
"currency_code": "EUR"
},
"destination": {
"type": "BANK_ACCOUNT",
"id": "bact:cgvL1yv43VFjexample"
},
"version": 1,
"type": "BATCH",
"arrival_date": "2021-07-13"
}
]
}
By default, results are returned from oldest to newest (or Z to A) in descending order. To switch to ascending order, set sort_order
to ASC
. For more details, see SortOrder.
To see payouts in a specific time range, specify the dates in the following format (see Working with Dates):
1
2
3
4
curl https://connect.squareupsandbox.com/v2/payouts?location_id={{LOCATION_ID}}&status=SENT&begin_time=2020-07-26T19%3A08%3A30Z&end_time=2021-07-26T19%3A08%3A30Z \
-H 'Square-Version: 2023-03-15' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json'
The following is an example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
{
"payouts": [
{
"id": "po_dd590570-ee44-11eb-a8bb-02420a140009",
"status": "SENT",
"location_id": "{LOCATION_ID}",
"created_at": "2021-07-26T19:08:30Z",
"updated_at": "2021-07-26T19:08:30Z",
"amount_money": {
"amount": 91,
"currency_code": "EUR"
},
"destination": {
"type": "BANK_ACCOUNT",
"id": "bact:cgvL1yv43VFjexample"
},
"version": 1,
"type": "BATCH"
},
{
"id": "po_dd5909a2-ee44-11eb-a8bb-02420a140009",
"status": "SENT",
"location_id": "{LOCATION_ID}",
"created_at": "2021-07-26T19:08:30Z",
"updated_at": "2021-07-26T19:08:30Z",
"amount_money": {
"amount": 239,
"currency_code": "EUR"
},
"destination": {
"type": "BANK_ACCOUNT",
"id": "bact:cgvL1yv43VFjexample"
},
"version": 1,
"type": "BATCH"
},
{
"id": "po_070431e4-e351-11eb-a8bb-02420a140009",
"status": "SENT",
"location_id": "{LOCATION_ID}",
"created_at": "2021-07-12T20:37:51Z",
"updated_at": "2022-03-27T20:37:51Z",
"amount_money": {
"amount": 457,
"currency_code": "EUR"
},
"destination": {
"type": "BANK_ACCOUNT",
"id": "bact:cgvL1yv43VFjexample"
},
"version": 1,
"type": "BATCH",
"arrival_date": "2021-07-13"
}
]
}
The payout_fee
field is the charge incurred to the seller for certain payouts. In the following example, the payout_fee
is 75 cents for an instant transfer:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
"id": "po_5defff0e-3f70-4977-8034-9eaf650f1156",
"status": "SENT",
"location_id": "{LOCATION_ID}",
"created_at": "2022-02-25T21:58:37Z",
"updated_at": "2022-02-25T21:58:37Z",
"amount_money": {
"amount": 4928,
"currency_code": "USD"
},
"destination": {
"type": "CARD",
"id": "ccof:IpqfhXp0mDydFAiI4GB"
},
"version": 1,
"type": "BATCH",
"payout_fee": [
{
"amount_money": {
"amount": 75,
"currency_code": "USD"
},
"effective_at": "2022-02-25T21:58:37Z",
"type": "TRANSFER_FEE"
}
],
"arrival_date": "2022-02-25"
}
For more information about transfer fees, see Transfer your application fee money.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.