Payouts API

List Payout Entries

The ListPayoutEntries endpoint provides a list of payout entries associated with a specific payout. You need to pass payout-entries as an argument to this endpoint. To call this endpoint, set PAYOUTS_READ for the OAuth scope.

Overview
Payout entry type details
Example: Retrieve taxes and tips
Related topics

Link to section
Overview

Payout entries are the individual transactions that are part of each payout. Chargebacks, refunds, and disputes appear independently as payout entries. If a seller is paying for Square SaaS products, the subscription fee payment appears as a payout entry as well.

You can order the payout entries in ascending or descending order. You cannot, however, retrieve a specific payout entry.

Similar to the ListPayouts endpoint, the ListPayoutEntries endpoint supports pagination.

List Payout Entries

curl https://connect.squareupsandbox.com/v2/payouts/{{PAYOUT_ID}}/payout-entries \
  -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

{
  "payout_entries": [
    {
      "id": "poe_5DhstmLsgJD0x3Cym3Cnislc0KM",
      "payout_id": "po_070431e4-e351-11eb-a8bb-02420a140009",
      "effective_at": "2021-07-08T08:41:27Z",
      "type": "CHARGE",
      "gross_amount_money": {
        "amount": 300,
        "currency_code": "EUR"
      },
      "fee_amount_money": {
        "amount": 25,
        "currency_code": "EUR"
      },
      "net_amount_money": {
        "amount": 275,
        "currency_code": "EUR"
      },
      "type_charge_details": {
        "payment_id": "PN5zqrHRbWR8fLkgVarzGaW9TYMZY"
      }
    },
    {
      "id": "poe_EOmSnV5uar_z06m2AvY0wTvHwVg",
      "payout_id": "po_070431e4-e351-11eb-a8bb-02420a140009",
      "effective_at": "2021-07-08T08:34:49Z",
      "type": "CHARGE",
      "gross_amount_money": {
        "amount": 100,
        "currency_code": "EUR"
      },
      "fee_amount_money": {
        "amount": 18,
        "currency_code": "EUR"
      },
      "net_amount_money": {
        "amount": 82,
        "currency_code": "EUR"
      },
      "type_charge_details": {
        "payment_id": "LVkuK15FwYPjRdmVXetEo15oUUKZY"
      }
    },
    {
      "id": "poe_q6wpw3W-VD7PVvmvXUduMy-zCTY",
      "payout_id": "po_070431e4-e351-11eb-a8bb-02420a140009",
      "effective_at": "2021-06-10T21:54:15Z",
      "type": "ADJUSTMENT",
      "gross_amount_money": {
        "amount": 100,
        "currency_code": "EUR"
      },
      "fee_amount_money": {
        "amount": 0,
        "currency_code": "EUR"
      },
      "net_amount_money": {
        "amount": 100,
        "currency_code": "EUR"
      }
    }
  ]
}

Link to section
Payout entry type details

The type_<payout entry type>_details field in a payout entry contains information specific to the type of the payout entry.

For the following types of payout entries, you can call other APIs using the type_<payout entry type>_details IDs to get more information:

Link to section
Charge

In the following example, the type_charge_details field represents a payout entry that captures a credit card payment.

To get details about the payment, you can use the payment_id with the Payments API.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
  "id": "poe_HbXoYjVE-_AQKvdp0TGnQ9fEntk",
  "payout_id": "po_d001cb2c-82cd-11ec-b8a4-02420a140004",
  "effective_at": "2022-01-31T21:54:06Z",
  "type": "CHARGE",
  "gross_amount_money": {
    "amount": 3500,
    "currency_code": "EUR"
  },
  "fee_amount_money": {
    "amount": 88,
    "currency_code": "EUR"
  },
  "net_amount_money": {
    "amount": 3412,
    "currency_code": "EUR"
  },
  "type_charge_details": {
    "payment_id": "HDGbMKeaLsW8YM8n6JxTyLwMDsaZY"
  }
}

Link to section
Open Dispute

In the following example, the type_open_dispute_details field represents a payout entry that is a balance change for a dispute that has been filed.

To get details about the payment, use the payment_id with the Payments API. To get details about the dispute, use the dispute_id with the Disputes API.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "id": "poe_i-HgL1RCBGsP2N5QoY8_vhghcxs",
  "payout_id": "po_d001cb2c-82cd-11ec-b8a4-02420a140004",
  "effective_at": "2022-01-31T19:27:14Z",
  "type": "OPEN_DISPUTE",
  "gross_amount_money": {
    "amount": -3500,
    "currency_code": "EUR"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "EUR"
  },
  "net_amount_money": {
    "amount": -3500,
    "currency_code": "EUR"
  },
  "type_open_dispute_details": {
    "payment_id": "HDGbMKeaLsW8YM8n6JxTyLwMDsaZY",
    "dispute_id": "KqE9hONQJP0pNXfZF2529C"
  }
}

Link to section
Refund

In the following example, the type_refund_details field represents a payout entry that is a refund.

To get details about the payment, use the payment_id with the Payments API. To get details about the refund, use the refund_id with the Refunds API.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "id": "poe_DlOuGQKZqeqtuxUFH7kTIQf-Ru0",
  "payout_id": "po_989fdac5-7fa9-11ec-b8a4-02420a140004",
  "effective_at": "2022-01-26T21:11:22Z",
  "type": "REFUND",
  "gross_amount_money": {
    "amount": -900,
    "currency_code": "EUR"
  },
  "fee_amount_money": {
    "amount": -22,
    "currency_code": "EUR"
  },
  "net_amount_money": {
    "amount": -878,
    "currency_code": "EUR"
  },
  "type_refund_details": {
    "payment_id": "9grVCDftT49xU70ZEUbGf8ZRkIYZY",
    "refund_id": "9grVCDftT49xU70ZEUbGf8ZRkIYZY_O0NJguMozbaUIdkrWegpRbkRlT23PW7CsFORgrFcCXZ"
  }
}

For a full list and definitions, see Payouts API Reference.

Link to section
Example: Retrieve taxes and tips

For charges or refunds, you can retrieve the total taxes and tip amounts, where applicable, using the additional details that you get back in a payout entry.

For example, in the following payout entry, the payment_id of F2eGGWCJZYf4sm4C3g9ial4sepWZY from the type_charge_details field represents the payment:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
    "id": "poe_NX06xUOxO2g2R6toBgRnMKO8cg4",
    "payout_id": "po_4a8bbd61-8ae0-4b92-86e9-76b487b10481",
    "effective_at": "2022-01-26T22:07:46Z",
    "type": "CHARGE",
    "gross_amount_money": {
        "amount": 1000,
        "currency_code": "USD"
    },
    "fee_amount_money": {
        "amount": 50,
        "currency_code": "USD"
    },
    "net_amount_money": {
        "amount": 950,
        "currency_code": "USD"
    },
    "type_charge_details": {
        "payment_id": "F2eGGWCJZYf4sm4C3g9ial4sepWZY"
    }
}

You can retrieve the payment by using the v2/payments/F2eGGWCJZYf4sm4C3g9ial4sepWZY endpoint.

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

{
  "payment": {
    "id": "F2eGGWCJZYf4sm4C3g9ial4sepWZY",
    "created_at": "2022-01-26T20:07:45.491Z",
    "updated_at": "2022-01-26T20:07:47.927Z",
    "amount_money": {
      "amount": 1000,
      "currency": "USD"
    },
     ...
    "location_id": "LCRS9JV5GZ9AZ",
    "order_id": "vhZTpadtU5FPT4JaIWBMMEvVFFTZY",
    "processing_fee": [
      {
        "effective_at": "2022-01-26T22:07:46.000Z",
        "type": "INITIAL",
        "amount_money": {
          "amount": 50,
          "currency": "USD"
        }
      }
    ],
    "customer_id": "BXRNCQ6T94T6Z27RMCD8KS8B14",
    "total_money": {
      "amount": 1000,
      "currency": "USD"
    },
    "approved_money": {
      "amount": 1000,
      "currency": "USD"
    },
     ...
  }
}

With the order ID from the Payment object, you can use the orders endpoint (v2/orders/vhZTpadtU5FPT4JaIWBMMEvVFFTZY) to retrieve the order information containing the taxes and tips. For more information, see RetrieveOrder.

Link to section
Related topics

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

Docs

List Payout Entries

On this page

Link to section
Overview

Link to section
Payout entry type details

Link to section
Charge

Link to section
Open Dispute

Link to section
Refund

Link to section
Example: Retrieve taxes and tips

Link to section
Related topics

On this page

Docs

List Payout Entries

On this page

Link to section Overview

Link to section Payout entry type details

Link to section Charge

Link to section Open Dispute

Link to section Refund

Link to section Example: Retrieve taxes and tips

Link to section Related topics

On this page

Link to section
Overview

Link to section
Payout entry type details

Link to section
Charge

Link to section
Open Dispute

Link to section
Refund

Link to section
Example: Retrieve taxes and tips

Link to section
Related topics