List Payout Entries

Applies to: Payouts API | Orders API

Learn how to retrieve a list of payout entries associated with a specific payout.

Overview

A payout is a transfer of funds from a seller's Square account to another banking destination. This is most often the seller’s external bank account. A payout generates a Payout object and corresponding PayoutEntry objects.

A PayoutEntry details the individual transactions included in a Payout. PayoutEntry objects can be retrieved using the ListPayoutEntries endpoint.

Link to section

How to use the endpoint

Important

To call ListPayoutEntries, your application needs to ask the sellers who install it for permission to read data about their payouts. Specify PAYOUTS_READ for the OAuth scope. For more information, see OAuth API.

Pass the payout_id of the target Payout as a path parameter, as in /payouts/{payout_id}/payout-entries. You can retrieve the payout_id from a call to ListPayouts.

The following example requests all payout entries associated with the payout with the ID po_1234567890abcdef:

curl https://connect.squareup.com/v2/payouts/po_1234567890abcdef/payout-entries \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

Square responds with a PayoutEntry like the following. The example payout_entries array includes two objects that represent a credit card charge of $150 and a refund of $50, respectively.

{
  "payout_entries": [
    {
      "id": "poe_1a2b3c4d5e6f7g8h9i0j",
      "payout_id": "po_12345678-90ab-cdef-1234-567890abcdef",
      "effective_at": "2022-03-24T03:07:09Z",
      "type": "CHARGE",
      "gross_amount_money": {
        "amount": 15000,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 465,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": 14535,
        "currency_code": "USD"
      },
      "type_charge_details": {
        "payment_id": "HVdG62H5K3291d0SGJS6IWd4cSi8YY"
      }
    },
    {
      "id": "poe_0a1b2c3d4e5f6g7h8i9j",
      "payout_id": "po_abcdef12-3456-7890-abcd-ef1234567890",
      "effective_at": "2022-03-24T03:07:09Z",
      "type": "REFUND",
      "gross_amount_money": {
        "amount": -5000,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 0,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": -5000,
        "currency_code": "USD"
      },
      "type_refund_details": {
        "payment_id": "ZVdG62HeMlti8YYf94oxrZ",
        "refund_id": "ZVdG62HeMlti8YYf94oxrN_dR8Nztxg7umf94oxrN12Ji5r2KW14FAZ"
      }
    }
  ]
}

Note

For comprehensive definitions of each PayoutEntry response object field, see API Reference.

Did you know?

The ListPayoutEntries endpoint supports pagination.

Link to section

How to use the _details field

The _details response field includes any additional information about the payout entry, if available. You can use this information in subsequent requests to other endpoints to learn more about the transaction.

For example, the following PayoutEntry represents a credit card charge of $150:

{
  "payout_entries": [
    {
      "id": "poe_1a2b3c4d5e6f7g8h9i0j",
      "payout_id": "po_12345678-90ab-cdef-1234-567890abcdef",
      "effective_at": "2022-03-24T03:07:09Z",
      "type": "CHARGE",
      "gross_amount_money": {
        "amount": 15000,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 465,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": 14535,
        "currency_code": "USD"
      },
      "type_charge_details": {
        "payment_id": "HVdG62H5K3291d0SGJS6IWd4cSi8YY"
      }
    }
  ]
}

You can use the payment_id returned under type_charge_details to retrieve the Payment object for the transaction. Pass the ID as a path parameter in a request to GetPayment, as in /payments/{payment_id}.

The following example requests shows details about the payment with the ID HVdG62H5K3291d0SGJS6IWd4cSi8YY:

curl https://connect.squareup.com/v2/payments/HVdG62H5K3291d0SGJS6IWd4cSi8YY \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

Square returns a Payment object. You can use the response details to look up even more information. For example, if the payment includes an associated order ID, you can call RetrieveOrder to get details such as any corresponding taxes or tips.

Important

Not all payout entry types include _details. All possible _details values are listed in the ListPayoutEntries API Reference.

Link to section

PayoutEntry types

Every PayoutEntry includes a type field that indicates the type of transaction that generated the entry.

The following payout entry types are supported:

A - G

H - P

R - Z

Link to section

ADJUSTMENT

A manual adjustment applied to the seller's account by Square.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-18T22:26:33Z",
  "type": "ADJUSTMENT",
  "gross_amount_money": {
    "amount": -2500,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": -2500,
    "currency_code": "USD"
  }
}

Link to section

APP_FEE_REFUND

A refund for an application fee on a payment.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-01-05T18:20:44Z",
  "type": "APP_FEE_REFUND",
  "gross_amount_money": {
    "amount": -40,
    "currency_code": "EUR"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "EUR"
  },
  "net_amount_money": {
    "amount": -40,
    "currency_code": "EUR"
  },
 "type_app_fee_refund_details": {
    "payment_id": "{payment_id}",
    "location_id": "{location_id}"
  }
}

Link to section

APP_FEE_REVENUE

Revenue generated from an application fee on a payment.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-01-05T18:20:44Z",
  "type": "APP_FEE_REVENUE",
  "gross_amount_money": {
    "amount": 100,
    "currency_code": "EUR"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "EUR"
  },
  "net_amount_money": {
    "amount": 100,
    "currency_code": "EUR"
  },
  "type_app_fee_revenue_details": {
    "payment_id": "{payment_id}",
    "location_id": "{location_id}"
  }
}

Link to section

AUTOMATIC_BITCOIN_CONVERSIONS

Indicates that the portion of each payment withheld by Square was automatically converted into bitcoin using Cash App. The seller manages their bitcoin in their Cash App account.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-04T20:22:06Z",
  "type": "AUTOMATIC_BITCOIN_CONVERSIONS",
  "gross_amount_money": {
    "amount": -858,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": -858,
    "currency_code": "USD"
  }
}

Link to section

AUTOMATIC_BITCOIN_CONVERSIONS_REVERSED

Indicates that a withheld payment, which was scheduled to be converted into bitcoin using Cash App, was deposited back to the Square payments balance.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-04T21:22:06Z",
  "type": "AUTOMATIC_BITCOIN_CONVERSIONS_REVERSED",
  "gross_amount_money": {
    "amount": 858,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": 858,
    "currency_code": "USD"
  }
}

Link to section

AUTOMATIC_SAVINGS

An automatic transfer from the payment processing balance to the Square Savings account. These are generally proportional to the seller's sales.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-25T17:13:40Z",
  "type": "AUTOMATIC_SAVINGS",
  "gross_amount_money": {
    "amount": -702,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": -702,
    "currency_code": "USD"
  },
  "type_automatic_savings_details": {
    "payment_id": "{payment_id}",
    "payout_id": "{payout_id}"
  }
}

Link to section

AUTOMATIC_SAVINGS_REVERSED

An automatic transfer from the Square Savings account back to the processing balance. These are generally proportional to the seller's refunds.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-25T17:15:40Z",
  "type": "AUTOMATIC_SAVINGS_REVERSED",
  "gross_amount_money": {
    "amount": 702,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": 702,
    "currency_code": "USD"
  },
  "type_automatic_savings_reversed_details": {
    "payment_id": "{payment_id}",
    "payout_id": "{payout_id}"
  }
}

Link to section

BALANCE_FOLDERS_TRANSFER

A transfer of funds to a banking folder. In the United States, the folder name is 'Checking Folder'; in Canada, it's 'Balance Folder'.

{
  "payout_entries": [
    {
      "id": "{id}",
      "payout_id": "{payout_id}",
      "effective_at": "2024-02-13T00:46:17Z",
      "type": "BALANCE_FOLDERS_TRANSFER",
      "gross_amount_money": {
        "amount": -5,
        "currency_code": "CAD"
      },
      "fee_amount_money": {
        "amount": 0,
        "currency_code": "CAD"
      },
      "net_amount_money": {
        "amount": -5,
        "currency_code": "CAD"
      }
    }
  ]
}

The following is an example of a SIMPLE type payout:

{
  "payout": {
    "id": "{id}",
    "status": "PAID",
    "location_id": "{location_id}",
    "created_at": "2024-02-12T00:44:14Z",
    "updated_at": "2024-02-12T01:44:28.667Z",
    "amount_money": {
      "amount": 5,
      "currency_code": "CAD"
    },
    "destination": {
      "type": "SQUARE_STORED_BALANCE",
      "id": ""
    },
    "version": 2,
    "type": "SIMPLE",
    "arrival_date": "2024-02-11",
    "number_of_entries": 0
  }
}

Link to section

BALANCE_FOLDERS_TRANSFER_REVERSED

A reversal of the transfer of funds from a banking folder. In the United States, the folder name is 'Checking Folder'; in Canada, it's 'Balance Folder'.

{
  "payout_entries": [
    ...
    {
      "id": "{id}",
      "payout_id": "{payout_id}",
      "effective_at": "2024-02-13T00:46:17Z",
      "type": "BALANCE_FOLDERS_TRANSFER_REVERSED",
      "gross_amount_money": {
        "amount": 5,
        "currency_code": "CAD"
      },
      "fee_amount_money": {
        "amount": 0,
        "currency_code": "CAD"
      },
      "net_amount_money": {
        "amount": 5,
        "currency_code": "CAD"
      }
    }
  ]
}

The following is an example of a SIMPLE type payout:

{
  "payout": {
    "id": "{id}",
    "status": "PAID",
    "location_id": "{location_id}",
    "created_at": "2024-02-12T00:44:14Z",
    "updated_at": "2024-02-12T01:44:28.667Z",
    "amount_money": {
      "amount": -5,
      "currency_code": "CAD"
    },
    "destination": {
      "type": "SQUARE_STORED_BALANCE",
      "id": ""
    },
    "version": 2,
    "type": "SIMPLE",
    "arrival_date": "2024-02-11",
    "number_of_entries": 0
  }
}

Link to section

CHARGE

A credit card payment capture.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-01-05T18:20:44Z",
  "type": "CHARGE",
  "gross_amount_money": {
    "amount": 1000,
    "currency_code": "EUR"
  },
  "fee_amount_money": {
    "amount": 54,
    "currency_code": "EUR"
  },
  "net_amount_money": {
    "amount": 946,
    "currency_code": "EUR"
  },
  "type_charge_details": {
    "payment_id": "{payment_id}"
  }
}

Link to section

CREDIT_CARD_REPAYMENT

Indicates that a repayment toward the outstanding balance on the seller's Square credit card was made.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-28T22:13:30Z",
  "type": "CREDIT_CARD_REPAYMENT",
  "gross_amount_money": {
    "amount": -1077,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": -1077,
    "currency_code": "USD"
  }
}

Link to section

CREDIT_CARD_REPAYMENT_REVERSED

Indicates that a repayment toward the outstanding balance on the seller's Square credit card was reversed.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-28T22:23:30Z",
  "type": "CREDIT_CARD_REPAYMENT_REVERSED",
  "gross_amount_money": {
    "amount": 1077,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": 1077,
    "currency_code": "USD"
  }
}

Link to section

DEPOSIT_FEE

A PayoutEntry has a type of DEPOSIT_FEE if the entry represents the service fee associated with an Instant Deposit. A seller triggers an Instant Deposit from the Square Dashboard or the Square Point of Sale application.

The following example PayoutEntry object represents a $1.26 fee for an Instant Deposit:

{
"id": "poe_GwriiDHHhkgs8kqfQg1bkA2GUxs",
"payout_id": "po_6542107a-323c-6a93-b9df-cggg3949b7e",
"effective_at": "2025-01-23T22:04:59Z",
"type": "DEPOSIT_FEE",
"gross_amount_money": {
  "amount": -126,
  "currency_code": "USD"
},
"fee_amount_money": {
  "amount": 0,
  "currency_code": "USD"
},
"net_amount_money": {
  "amount": -126,
  "currency_code": "USD"
},
"type_deposit_fee_details": {
  "payout_id": "po_6542107a-323c-6a93-b9df-cggg3949b7e"
}
}

Note

The service fee for a Scheduled Deposit, a type of Instant Deposit, also has a payout entry type of DEPOSIT_FEE.

Link to section

DEPOSIT_FEE_REVERSED

Indicates that Square returned a fee that was previously assessed because of a deposit, such as an instant deposit, back to the seller's account.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-24T20:03:08Z",
  "type": "DEPOSIT_FEE_REVERSED",
  "gross_amount_money": {
    "amount": 26,
    "currency_code": "AUD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "AUD"
  },
  "net_amount_money": {
    "amount": 26,
    "currency_code": "AUD"
  },
  "type_deposit_fee_reversed_details": {
    "payout_id": "{payout_id}"
  }
}

Link to section

DISPUTE

The balance change due to a dispute event.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-18T21:37:37Z",
  "type": "DISPUTE",
  "gross_amount_money": {
    "amount": 5000,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": 5000,
    "currency_code": "USD"
  },
  "type_dispute_details": {
    "payment_id": "{payment_id}"
  }
}

Link to section

ESCHEATMENT

An escheatment entry for remittance.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-05-18T02:11:24Z",
  "type": "ESCHEATMENT",
  "gross_amount_money": {
    "amount": -4022,
    "currency_code": "AUD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "AUD"
  },
  "net_amount_money": {
    "amount": -4022,
    "currency_code": "AUD"
  }
}

Link to section

FEE

A PayoutEntry has a type of FEE if the entry represents a Cost Plus fee adjustment.

Cost Plus is a custom pricing plan that a seller negotiates with Square. Under Cost Plus, Square charges an estimated fee at the time of each transaction. At the end of the month, Square makes a one-time adjustment to capture the final fee. This one-time adjustment is represented as a PayoutEntry with the type of FEE.

For example, Square charges an initial estimated $1 fee for a transaction at the beginning of a month. At the end of the month, after the Cost Plus adjustment, the final fee for the transaction is only $0.75. Square returns $0.25 to the seller.

The PayoutEntry for the $0.25 Cost Plus fee adjustment takes the following shape:

{
  "payout_entries": [
    {
      "id": "poe_1234567890abcdef1234567890abcdef",
      "payout_id": "po_abcdef1234567890abcdef1234567890",
      "effective_at": "2022-03-24T03:07:09Z",
      "type": "FEE",
      "gross_amount_money": {
        "amount": 25,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 0,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": 25,
        "currency_code": "USD"
      },
      "type_fee_details": {
        "payment_id": "JkL9M8N7O6P5Q4R3S2T1U0V9W8X7Y6Z5"
      }
    }
  ]
}

The payment_id is the ID associated with the CHARGE PayoutEntry for the original transaction at the beginning of the month.

Link to section

FREE_PROCESSING

Square offers free payments processing for a variety of business scenarios, including seller referrals or when Square wants to apologize (for example, for a bug, customer service, or repricing complication). This entry represents a credit to the seller for the purposes of free processing.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-07T20:52:22Z",
  "type": "FREE_PROCESSING",
  "gross_amount_money": {
    "amount": 190,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": 190,
    "currency_code": "USD"
  },
  "type_free_processing_details": {
    "payment_id": "{payment_id}"
  }
}

Link to section

GIFT_CARD_LOAD_FEE

The fee collected during the sale or reload of a gift card. This fee, which is a portion of the amount loaded on the gift card, is deducted from the merchant's payment balance.

{
  "payout_entries": [
    {
      "id": "{id}",
      "payout_id": "{payout_id}",
      "effective_at": "2024-02-09T20:44:05Z",
      "type": "GIFT_CARD_LOAD_FEE",
      "gross_amount_money": {
        "amount": -125,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 0,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": -125,
        "currency_code": "USD"
      }
    },
  ]
}

Link to section

GIFT_CARD_LOAD_FEE_REFUND

The refund for a fee charged during the sale or reload of a gift card.

{
  "payout_entries": [
    {
      "id": "{id}",
      "payout_id": "{payout_id}",
      "effective_at": "2024-02-10T22:34:34Z",
      "type": "GIFT_CARD_LOAD_FEE_REFUND",
      "gross_amount_money": {
        "amount": 28,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 0,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": 28,
        "currency_code": "USD"
      }
    }
  ]
}

Link to section

GIFT_CARD_POOL_TRANSFER

A transfer of gift card funds to a central gift card pool account. In franchises, when gift cards are loaded or reloaded at any location, the money transfers to the franchisor's account.

{
  "payout_entries": [
    {
      "id": "{id}",
      "payout_id": "{payout_id}",
      "effective_at": "2024-01-11T18:43:29Z",
      "type": "GIFT_CARD_POOL_TRANSFER",
      "gross_amount_money": {
        "amount": -4700,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 0,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": -4700,
        "currency_code": "USD"
      }
    },
  ]
}

Link to section

GIFT_CARD_POOL_TRANSFER_REVERSED

A reversal of the transfer of gift card funds from a central gift card pool account. In franchises, when gift cards are loaded or reloaded at any location, the money transfers to the franchisor's account.

{
  "payout_entries": [
    {
      "id": "{id}",
      "payout_id": "{payout_id}",
      "effective_at": "2024-01-11T18:43:29Z",
      "type": "GIFT_CARD_POOL_TRANSFER_REVERSED",
      "gross_amount_money": {
        "amount": 4700,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 0,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": -4700,
        "currency_code": "USD"
      }
    },
  ]
}

Link to section

HOLD_ADJUSTMENT

An adjustment made by Square related to holding a payment.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-10T19:29:37Z",
  "type": "HOLD_ADJUSTMENT",
  "gross_amount_money": {
    "amount": -1000,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": -1000,
    "currency_code": "USD"
  },
  "type_hold_adjustment_details": {
    "payment_id": "{payment_id}"
  }
}

Link to section

INITIAL_BALANCE_CHANGE

An external change to a seller's balance (in the sense that it causes the creation of the other activity types, such as a hold and refund).

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-02-08T21:53:41Z",
  "type": "INITIAL_BALANCE_CHANGE",
  "gross_amount_money": {
    "amount": 10000,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": 10000,
    "currency_code": "USD"
  }
}

Link to section

LOCAL_OFFERS_CASHBACK

The cashback amount given by a Square Local Offers seller to their customer for a purchase.

{
  "payout_entries": [
    {
      "id": "{id}",
      "payout_id": "{payout_id}",
      "effective_at": "2024-02-08T15:49:45Z",
      "type": "LOCAL_OFFERS_CASHBACK",
      "gross_amount_money": {
        "amount": -50,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 0,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": -50,
        "currency_code": "USD"
      }
    }
  ]
}

Link to section

LOCAL_OFFERS_FEE

A commission fee paid by a Square Local Offers seller to Square for a purchase discovered through Square Local Offers.

{
  "payout_entries": [
    {
      "id": "{id}",
      "payout_id": "{payout_id}",
      "effective_at": "2024-02-08T15:49:45Z",
      "type": "LOCAL_OFFERS_FEE",
      "gross_amount_money": {
        "amount": -20,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 0,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": -20,
        "currency_code": "USD"
      }
    }
  ]
}

Link to section

MONEY_TRANSFER

The balance change from a money transfer.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-05-29T20:14:11Z",
  "type": "MONEY_TRANSFER",
  "gross_amount_money": {
    "amount": 440,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": 440,
    "currency_code": "USD"
  }
}

Link to section

MONEY_TRANSFER_REVERSAL

The reversal of a money transfer.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-05-29T16:46:55Z",
  "type": "MONEY_TRANSFER_REVERSAL",
  "gross_amount_money": {
    "amount": -440,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": -440,
    "currency_code": "USD"
  }
}

Link to section

OPEN_DISPUTE

The balance change for a chargeback that's been filed.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-17T21:37:37Z",
  "type": "OPEN_DISPUTE",
  "gross_amount_money": {
    "amount": -5000,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": -5000,
    "currency_code": "USD"
  },
  "type_open_dispute_details": {
    "payment_id": "{payment_id}",
    "dispute_id": "{dispute_id}"
  }
}

Link to section

OTHER

Any other type that doesn't belong in the rest of the types.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-03-28T20:52:45Z",
  "type": "OTHER",
  "gross_amount_money": {
    "amount": -30,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": -30,
    "currency_code": "USD"
  },
  "type_other_details": {
    "payment_id": "{payment_id}"
  }
}

Link to section

OTHER_ADJUSTMENT

Any other type of adjustment that doesn't fall under existing types.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2022-02-22T10:23:15Z",
  "type": "OTHER_ADJUSTMENT",
  "gross_amount_money": {
    "amount": 2426,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": 2426,
    "currency_code": "USD"
  }
}

Link to section

PAID_SERVICE_FEE

A fee paid to a third-party seller.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2022-10-02T07:58:31Z",
  "type": "PAID_SERVICE_FEE",
  "gross_amount_money": {
    "amount": -500,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": -500,
    "currency_code": "USD"
  }
}

Link to section

PAID_SERVICE_FEE_REFUND

A fee refunded to a third-party seller.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2022-10-18T17:20:45Z",
  "type": "PAID_SERVICE_FEE_REFUND",
  "gross_amount_money": {
    "amount": 290,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": 290,
    "currency_code": "USD"
  }
}

Link to section

PAYOUT

The balance change due to a money transfer. Note that this type is never returned by the Payouts API.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-18T14:50:22Z",
  "type": "PAYOUT",
  "gross_amount_money": {
    "amount": 1950,
    "currency_code": "GBP"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "GBP"
  },
  "net_amount_money": {
    "amount": 1950,
    "currency_code": "GBP"
  }
}

Link to section

PERCENTAGE_PROCESSING_DEACTIVATION

Deducting the outstanding Percentage Processing balance from the seller’s account. It's the final installment in repaying the dispute-induced negative balance through percentage processing.

{
  "payout_entries": [
    {
      "id": "{id}",
      "payout_id": "{payout_id}",
      "effective_at": "2023-12-19T02:40:21Z",
      "type": "PERCENTAGE_PROCESSING_DEACTIVATION",
      "gross_amount_money": {
        "amount": -91231,
        "currency_code": "GBP"
      },
      "fee_amount_money": {
        "amount": 0,
        "currency_code": "GBP"
      },
      "net_amount_money": {
        "amount": -91231,
        "currency_code": "GBP"
      }
    }
  ]
}

Link to section

PERCENTAGE_PROCESSING_ENROLLMENT

When activating Percentage Processing, a credit is applied to the seller’s account to offset any negative balance caused by a dispute.

{
  "payout_entries": [
    {
      "id": "{id}",
      "payout_id": "{payout_id}",
      "effective_at": "2023-11-28T01:49:54Z",
      "type": "PERCENTAGE_PROCESSING_ENROLLMENT",
      "gross_amount_money": {
        "amount": 81600,
        "currency_code": "GBP"
      },
      "fee_amount_money": {
        "amount": 0,
        "currency_code": "GBP"
      },
      "net_amount_money": {
        "amount": 81600,
        "currency_code": "GBP"
      }
    }
  ]
}

Link to section

PERCENTAGE_PROCESSING_REPAYMENT

The withheld funds from a payment to cover a negative balance. It's an installment to repay the amount from a dispute that was offset during Percentage Processing enrollment.

{
  "payout_entries": [
    {
      "id": "{id}",
      "payout_id": "{payout_id}",
      "effective_at": "2023-12-18T07:51:14Z",
      "type": "PERCENTAGE_PROCESSING_REPAYMENT",
      "gross_amount_money": {
        "amount": -200,
        "currency_code": "GBP"
      },
      "fee_amount_money": {
        "amount": 0,
        "currency_code": "GBP"
      },
      "net_amount_money": {
        "amount": -200,
        "currency_code": "GBP"
      }
    }
  ]
}

Link to section

PERCENTAGE_PROCESSING_REPAYMENT_REVERSED

The reversal of a Percentage Processing repayment that happens, for example, when a refund is issued for a payment.

{
  "payout_entries": [
    {
      "id": "{id}",
      "payout_id": "{payout_id}",
      "effective_at": "2023-12-19T07:51:14Z",
      "type": "PERCENTAGE_PROCESSING_REPAYMENT_REVERSED",
      "gross_amount_money": {
        "amount": 200,
        "currency_code": "GBP"
      },
      "fee_amount_money": {
        "amount": 0,
        "currency_code": "GBP"
      },
      "net_amount_money": {
        "amount": 200,
        "currency_code": "GBP"
      }
    }
  ]
}

Link to section

PROCESSING_FEE

A PayoutEntry has a type of PROCESSING_FEE if the entry represents a Gross Settlement adjustment.

Gross Settlement is a custom pricing setup that a seller negotiates with Square. With Gross Settlement, Square doesn't charge transaction fees upfront. Instead, Square debits all processing fees in one lump sum on a monthly basis. This is generally on the 10th of every month, unless the seller and Square arrange otherwise.

For example, at the beginning of the month a seller processes a $34.62 transaction. Square doesn't charge a fee. At the end of the month, Square debits the seller a $0.75 fee for the transaction. The reconciliation PayoutEntry has a type of PROCESSING_FEE. The fee_amount_money value is always 0.

The $0.75 fee adjustment for a Gross Settlement PayoutEntry takes the following shape:

{
  "payout_entries": [
    {
      "id": "poe_1a2b3c4d5e6f7g8h9i0j",
      "payout_id": "po_1a2b3c4d5e6f7g8h9i0j",
      "effective_at": "2022-03-24T03:07:09Z",
      "type": "CHARGE",
      "gross_amount_money": {
        "amount": 3462,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 0,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": 3462,
        "currency_code": "USD"
      },
      "type_charge_details": {
        "payment_id": "XyZ9A8B7C6D5E4F3G2H1I0J9K8L7M6N5"
      }
    }
  ]
}

Link to section

PROCESSING_FEE_REFUND

The processing fee for a payment refund issued by sellers enrolled in Gross Settlement. The refunded processing fee is recorded separately as a new payout entry, not as part of the REFUND payout entry.

{
  "payout_entries": [
    {
      "id": "{id}",
      "payout_id": "{payout_id}",
      "effective_at": "2024-02-09T21:10:21Z",
      "type": "PROCESSING_FEE_REFUND",
      "gross_amount_money": {
        "amount": 85,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 0,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": 85,
        "currency_code": "USD"
      }
    }
  ]
}

Link to section

REDEMPTION_CODE

A repayment for a redemption code.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2022-03-17T19:35:22Z",
  "type": "REDEMPTION_CODE",
  "gross_amount_money": {
    "amount": 1000,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": 1000,
    "currency_code": "USD"
  }
}

Link to section

REFUND

A refund for an existing card payment.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-01-05T18:20:44Z",
  "type": "REFUND",
  "gross_amount_money": {
    "amount": -400,
    "currency_code": "EUR"
  },
  "fee_amount_money": {
    "amount": -12,
    "currency_code": "EUR"
  },
  "net_amount_money": {
    "amount": -388,
    "currency_code": "EUR"
  },
  "type_refund_details": {
    "payment_id": "{payment_id}",
    "refund_id": "{refund_id}"
  }
}

Link to section

RELEASE_ADJUSTMENT

An adjustment made by Square related to releasing a payment.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-21T18:00:00Z",
  "type": "RELEASE_ADJUSTMENT",
  "gross_amount_money": {
    "amount": 87,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": 87,
    "currency_code": "USD"
  },
  "type_release_adjustment_details": {
    "payment_id": "{payment_id}"
  }
}

Link to section

RESERVE_HOLD

Fees paid for a funding risk reserve.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-21T22:54:31Z",
  "type": "RESERVE_HOLD",
  "gross_amount_money": {
    "amount": -5000,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": -5000,
    "currency_code": "USD"
  },
  "type_reserve_hold_details": {
    "payment_id": "{payment_id}"
  }
}

Link to section

RESERVE_RELEASE

Fees released from a risk reserve.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-14T18:00:09Z",
  "type": "RESERVE_RELEASE",
  "gross_amount_money": {
    "amount": 2000,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": 2000,
    "currency_code": "USD"
  },
  "type_reserve_release_details": {
    "payment_id": "{payment_id}"
  }
}

Link to section

RETURNED_PAYOUT

An entry created when Square receives a response for the ACH file that Square sent indicating that the settlement of the original entry failed.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-18T14:50:22Z",
  "type": "RETURNED_PAYOUT",
  "gross_amount_money": {
    "amount": 1950,
    "currency_code": "GBP"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "GBP"
  },
  "net_amount_money": {
    "amount": 1950,
    "currency_code": "GBP"
  }
}

Link to section

SQUARE_CAPITAL_PAYMENT

A capital merchant cash advance (MCA) assessment. These are generally proportional to the merchant's sales but can be issued for other reasons related to the MCA.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-25T17:13:40Z",
  "type": "SQUARE_CAPITAL_PAYMENT",
  "gross_amount_money": {
    "amount": -2808,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": -2808,
    "currency_code": "USD"
  },
  "type_square_capital_payment_details": {
    "payment_id": "{payment_id}"
  }
}

Link to section

SQUARE_CAPITAL_REVERSED_PAYMENT

A capital merchant cash advance (MCA) assessment refund. These are generally proportional to the merchant's refunds but can be issued for other reasons related to the MCA.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-17T21:39:50Z",
  "type": "SQUARE_CAPITAL_REVERSED_PAYMENT",
  "gross_amount_money": {
    "amount": 162,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": 162,
    "currency_code": "USD"
  },
  "type_square_capital_reversed_payment_details": {
    "payment_id": "{payment_id}"
  }
}

Link to section

SQUARE_PAYROLL_TRANSFER

A payroll payment that was transferred to a team member's bank account.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-17T21:39:50Z",
  "type": "SQUARE_PAYROLL_TRANSFER",
  "gross_amount_money": {
    "amount": -858,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": -858,
    "currency_code": "USD"
  },
  "type_square_payroll_transfer_details": {
    "payment_id": "{payment_id}"
  }
}

Link to section

SQUARE_PAYROLL_TRANSFER_REVERSED

A payroll payment to a team member's bank account was deposited back to the seller's account by Square.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-17T21:39:50Z",
  "type": "SQUARE_PAYROLL_TRANSFER_REVERSED",
  "gross_amount_money": {
    "amount": 858,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": 858,
    "currency_code": "USD"
  },
  "type_square_payroll_transfer_reversed_details": {
    "payment_id": "{payment_id}"
  }
}

Link to section

SUBSCRIPTION_FEE

A fee charged for subscription to a Square product.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2022-09-01T15:01:23Z",
  "type": "SUBSCRIPTION_FEE",
  "gross_amount_money": {
    "amount": -3261,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": -3261,
    "currency_code": "USD"
  }
}

Link to section

SUBSCRIPTION_FEE_PAID_REFUND

A Square subscription fee that's been refunded.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2022-02-18T14:34:35Z",
  "type": "SUBSCRIPTION_FEE_PAID_REFUND",
  "gross_amount_money": {
    "amount": 980,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": 980,
    "currency_code": "USD"
  }
}

Link to section

SUBSCRIPTION_FEE_REFUND

The refund of a previously charged Square product subscription fee.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-16T15:00:22Z",
  "type": "SUBSCRIPTION_FEE_REFUND",
  "gross_amount_money": {
    "amount": 1900,
    "currency_code": "USD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "USD"
  },
  "net_amount_money": {
    "amount": 1900,
    "currency_code": "USD"
  }
}

Link to section

TAX_ON_FEE

The tax paid on fee amounts.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-04-23T04:30:05Z",
  "type": "TAX_ON_FEE",
  "gross_amount_money": {
    "amount": -1,
    "currency_code": "AUD"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "AUD"
  },
  "net_amount_money": {
    "amount": -1,
    "currency_code": "AUD"
  },
  "type_tax_on_fee_details": {
    "payment_id": "{payment_id}"
  }
}

Link to section

THIRD_PARTY_FEE

Fees collected by a third-party platform.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-01-05T18:20:44Z",
  "type": "THIRD_PARTY_FEE",
  "gross_amount_money": {
    "amount": -100,
    "currency_code": "EUR"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "EUR"
  },
  "net_amount_money": {
    "amount": -100,
    "currency_code": "EUR"
  },
  "type_third_party_fee_details": {
    "payment_id": "{payment_id}"
  }
}

Link to section

THIRD_PARTY_FEE_REFUND

Refunded fees from a third-party platform.

{
  "id": "{id}",
  "payout_id": "{payout_id}",
  "effective_at": "2023-01-05T18:20:44Z",
  "type": "THIRD_PARTY_FEE_REFUND",
  "gross_amount_money": {
    "amount": 40,
    "currency_code": "EUR"
  },
  "fee_amount_money": {
    "amount": 0,
    "currency_code": "EUR"
  },
  "net_amount_money": {
    "amount": 40,
    "currency_code": "EUR"
  },
  "type_third_party_fee_refund_details": {
    "payment_id": "{payment_id}"
  }
}

Link to section

UNDO_GIFT_CARD_LOAD_FEE_REFUND

The undoing of a refund for a fee charged during the sale or reload of a gift card.

{
  "payout_entries": [
    {
      "id": "{id}",
      "payout_id": "{payout_id}",
      "effective_at": "2024-01-11T19:22:33Z",
      "type": "UNDO_GIFT_CARD_LOAD_FEE_REFUND",
      "gross_amount_money": {
        "amount": -25,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 0,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": -25,
        "currency_code": "USD"
      },
      "type_other_details": {
        "payment_id": "BulHgSvkhNVMG4vqqbZI1q6O58YZY"
      }
    }
  ]
}

Link to section

UNDO_PROCESSING_FEE_REFUND

When undoing a processing fee refund in a Gross Settlement payment, this payout entry type is used.

{
  "payout_entries": [
    {
      "id": "{id}",
      "payout_id": "{payout_id}",
      "effective_at": "2024-02-09T21:13:04Z",
      "type": "UNDO_PROCESSING_FEE_REFUND",
      "gross_amount_money": {
        "amount": -85,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 0,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": -85,
        "currency_code": "USD"
      }
    }
  ]
}

Link to section

Docs

List Payout Entries

On this page

Overview

How to use the endpoint

Important

Note

Did you know?

How to use the _details field

Important

PayoutEntry types

ADJUSTMENT

APP_FEE_REFUND

APP_FEE_REVENUE

AUTOMATIC_BITCOIN_CONVERSIONS

AUTOMATIC_BITCOIN_CONVERSIONS_REVERSED

AUTOMATIC_SAVINGS

AUTOMATIC_SAVINGS_REVERSED

BALANCE_FOLDERS_TRANSFER

BALANCE_FOLDERS_TRANSFER_REVERSED

CHARGE

CREDIT_CARD_REPAYMENT

CREDIT_CARD_REPAYMENT_REVERSED

DEPOSIT_FEE

Note

DEPOSIT_FEE_REVERSED

DISPUTE

ESCHEATMENT

FEE

FREE_PROCESSING

GIFT_CARD_LOAD_FEE

GIFT_CARD_LOAD_FEE_REFUND

GIFT_CARD_POOL_TRANSFER

GIFT_CARD_POOL_TRANSFER_REVERSED

HOLD_ADJUSTMENT

INITIAL_BALANCE_CHANGE

LOCAL_OFFERS_CASHBACK

LOCAL_OFFERS_FEE

MONEY_TRANSFER

MONEY_TRANSFER_REVERSAL

OPEN_DISPUTE

OTHER

OTHER_ADJUSTMENT

PAID_SERVICE_FEE

PAID_SERVICE_FEE_REFUND

PAYOUT

PERCENTAGE_PROCESSING_DEACTIVATION

PERCENTAGE_PROCESSING_ENROLLMENT

PERCENTAGE_PROCESSING_REPAYMENT

PERCENTAGE_PROCESSING_REPAYMENT_REVERSED

PROCESSING_FEE

PROCESSING_FEE_REFUND

REDEMPTION_CODE

REFUND

RELEASE_ADJUSTMENT

RESERVE_HOLD

RESERVE_RELEASE

RETURNED_PAYOUT

SQUARE_CAPITAL_PAYMENT

SQUARE_CAPITAL_REVERSED_PAYMENT

SQUARE_PAYROLL_TRANSFER

SQUARE_PAYROLL_TRANSFER_REVERSED

SUBSCRIPTION_FEE

SUBSCRIPTION_FEE_PAID_REFUND

SUBSCRIPTION_FEE_REFUND

TAX_ON_FEE

THIRD_PARTY_FEE

THIRD_PARTY_FEE_REFUND

UNDO_GIFT_CARD_LOAD_FEE_REFUND

UNDO_PROCESSING_FEE_REFUND

See also

On this page