Migrate from the Square Settlements API
Deprecated
This component is deprecated. See below for guidance about what to use instead.
Learn how to migrate an application from the Settlements API to the Payouts API.
To view payout data prior to January 2021, you need to use the V1 Settlements API.
The Payouts API replaces the Settlements API and provides new functionality to make it easier to get a list of deposits and withdrawals from a seller's bank accounts.
Deprecation: 2019-11-15
Retirement: 2023-06-16
If you need help migrating to Square APIs or need more time to complete your migration, contact Developer Support, join our Discord community, or reach out to your Square account manager.
The Payouts API provides all the functionality of the Settlements API and adds these features:
ListPayoutEntries endpoint - The ListPayouts endpoint provides summary-level information while a new ListPayoutEntries endpoint retrieves a list of all payout entries for a specific payout. The Settlements API doesn't differentiate between summary-level payout information and specific payout entry information.
Permissions - The Payouts API supports a new
PAYOUTS_READ
permission that replaces theSETTLEMENTS_READ
permission for the OAuth scope. You can still use theSETTLEMENTS_READ
permission, but you should migrate to thePAYOUTS_READ
permission before Square retires theSETTLEMENTS_READ
permission on June 16, 2023.Transfer reporting scope - Payouts only show transfers from the Square balance to a seller's external bank account, a Square checking or savings account (available only in the United States), or a debit card (for instant transfers). Transfers from Square checking or savings account to an external bank account aren't reported by the Payouts API.
Pagination - The ListPayouts and ListPayoutEntries endpoints support pagination. You can specify the page size (the number of items to return in the response) using a
limit
field.Reporting of transfers to Square Checking or Square Card - The
total_amount
field in thePayout
object represents the sum of amounts of the individual transactions included in the payout. It excludes non-zero amount settlements for Square Checking (in the United States) or Square Card (in Canada). For more information, see Reporting of Square internal transfers.Manual transfers - For manual transfers, the Payouts API generates payouts with individual payout entries, whereas the Settlements API generates a single payout entry of the
OTHER
type.Payouts to Square Savings - SIMPLE payouts are created for all transfers to the Square Savings account (available only in the United States). These transfers show up as payout entries in the subsequent BATCH payout to deduct the amount of the SIMPLE payout.
Webhooks support - You can use webhooks in an application to get notification of a payout status change. For more information, see Square Webhooks Overview.
Sandbox support - You can create payments, refunds, or disputes using the Payments, Refunds, and Disputes APIs in the Sandbox environment and then retrieve the
Payout
objects containing those transactions on the next business day after you transfer the funds.
The Payouts API endpoints replace the ListSettlements
and RetrieveSettlements
functionality in the Settlements API.
Deprecated Settlements API endpoint | Payouts API replacement endpoint |
---|---|
ListSettlements | ListPayouts |
RetrieveSettlement | GetPayout and ListPayoutEntries |
The ListSettlements endpoint is replaced by the ListPayouts endpoint. The following sections provide mapping information about the path parameters, query parameters, and response fields.
The following table shows how the V1 ListSettlements
path parameters map to the ListPayouts
endpoint:
V1 ListSettlements path parameter | ListPayouts path parameter | Notes |
---|---|---|
location_id | N/A | location_id is changed to a query parameter. |
The following table shows how the V1 ListSettlements
query parameters map to the ListPayouts
endpoint:
V1 ListSettlements query parameter | ListPayouts query parameter | Notes |
---|---|---|
order | sort_order | |
begin_time | begin_time | No longer requires ISO 8601 format for the date time. Now requires RFC 3339 format. |
end_time | end_time | No longer requires ISO 8601 format for the date time. Now requires RFC 3339 format. |
limit | limit | |
status | status | New status type: PAID indicates that the payout has successfully completed. |
batch_token | cursor | |
N/A | location_id | The ID of the location associated with the payout. |
The ID schema for settlement_id
and payout_id
aren't the same. You cannot directly map a V1 settlement_id
to its corresponding payout_id
in the V2 Payouts API. If your application is syncing historical payout records, it might have synced a payout under a different ID with the Settlements API.
The V1 ListSettlements
endpoint returns settlement information as a Settlement object in the response body, whereas the ListPayouts
endpoint returns a Payouts object.
V1 ListSettlements field | ListPayouts field | Notes |
---|---|---|
items | payouts | The requested list of payouts. For more information, see Payouts. |
bank_account_id | destination | Banking destinations include bank accounts, Square checking accounts, or debit cards. For more information, see Destination. |
entries | N/A | A new ListPayoutEntries endpoint retrieves a list of all payout entries for a specific payout. |
initiated_at | created_at | The timestamp of when the payout was created and submitted for deposit to the seller's banking destination, in RFC 3339 format. |
status | status | New status type: PAID indicates that the payout has succeeded. |
total_money | amount_money | The amount of money involved in the payout. |
N/A | location_id | The ID of the location associated with the payout. |
N/A | arrival_date | The calendar date, in ISO 8601 format (YYYY-MM-DD), when the payout is due to arrive in the seller’s banking destination. |
N/A | payout_fee | A list of processing fees and any taxes on the fees assessed by Square for this payout. |
N/A | type | Indicates whether the payout is a BATCH or SIMPLE type. |
N/A | updated_at | The timestamp of when the payout was last updated, in RFC 3339 format. |
N/A | version | The version number, which is incremented each time an update is made to this payout record. |
The RetrieveSettlement endpoint is replaced by the GetPayout and ListPayoutEntries endpoints. The following sections provide mapping information about the path parameters, query parameters, and response fields.
The following table shows how the V1 RetrieveSettlement
path parameters map to the GetPayout
and ListPayoutEntries
endpoints:
V1 RetrieveSettlement path parameters | GetPayout and ListPayoutEntries path parameters |
---|---|
location_id | N/A |
settlement_id | payout_id |
The following table shows how the V1 RetrieveSettlement
query parameters map to the ListPayoutEntries
endpoint:
V1 RetrieveSettlement query parameters | ListPayoutEntries query parameters |
---|---|
N/A | sort_order |
N/A | cursor |
N/A | limit |
The following table compares the fields for the V1 RetrieveSettlement
and GetPayout
endpoints:
V1 RetrieveSettlement field | GetPayout field | Notes |
---|---|---|
N/A | payout | The requested payout. |
N/A | location_id | The ID of the location associated with the payout. |
status | status | New status type: PAID indicates that the payout has succeeded. |
total_money | amount_money | The amount of money involved in the payout. |
initiated_at | created_at | The timestamp of when the payout was created and submitted for deposit to the seller's banking destination, in RFC 3339 format. |
bank_account_id | destination | Banking destinations include bank accounts, Square checking accounts, or debit cards. For more information, see Destination. |
entries | N/A | A new ListPayoutEntries endpoint retrieves a list of all payout entries for a specific payout. |
N/A | arrival_date | The calendar date, in ISO 8601 format (YYYY-MM-DD), when the payout is due to arrive in the seller’s banking destination. |
N/A | payout_fee | A list of processing fees and any taxes on the fees assessed by Square for this payout. |
N/A | type | Indicates whether the payout is a BATCH or SIMPLE type. |
N/A | updated_at | The timestamp of when the payout was last updated, in RFC 3339 format. |
N/A | version | The version number, which is incremented each time an update is made to this payout record. |
The V1 RetrieveSettlement
endpoint returns entries information as a SettlementEntry object in the response body, whereas the ListPayoutEntries
endpoint returns a PayoutEntry object.
V1 RetrieveSettlement field | ListPayoutEntries field | Notes |
---|---|---|
amount_money | net_amount_money | The net proceeds from this transaction after any fees. |
fee_money | fee_amount_money | The amount of Square fees associated with this payout entry. |
N/A | gross_amount_money | The amount of money involved in this payout entry. |
N/A | payout_id | The ID of the payout entry associated payout. |
N/A | effective_at | The timestamp of when the payout entry affected the balance, in RFC 3339 format. |
N/A | type_{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 more information, see ListPayoutEntries. |
For transfers to Square Checking (in the United States) or Square Card (in Canada), the V1 Settlements API shows a settlement amount of 0
and includes the settled transactions and a negative amount entry labeled OTHER
. Alternatively, the Payouts API only shows entries that are transferred (for example, CHARGE
) and payout amounts are equal to the sum of the transferred entries.
The following example shows a V1 ListSettlements
response with an entry type of OTHER
and the settlement amount as 0
:
The following example shows a ListPayouts
response with the actual amount of the payout:
The following example shows a ListPayoutEntries
response with detailed information of the payout entry:
The following example shows a request to retrieve settlements for a location ID:
The following shows the ListSettlements
response:
Example ListPayouts request
The following example shows a request to list payouts for the default location:
The following shows the ListPayouts
response:
The following shows a GetSettlement
request to retrieve a specific settlement identified by a settlement ID:
The following shows the GetSettlement
response:
The following GetPayout
example shows a request to get details of a specific payout identified by a payout ID:
The following shows the GetPayout
response:
The following example shows a request to get a list of all payout entries for a specific payout:
The following shows the ListPayoutEntries
response:
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.