Payouts API

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.

List Payouts

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:

List Payouts

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):

List Payouts

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.

Link to section
Related topics

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Docs

List Payouts

Link to section Related topics

Link to section
Related topics