The Payouts API lets you see a list of deposits and withdrawals from a seller's banking destination.
A banking destination can be 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).
You can use the Payouts API to automatically reconcile transactions to and from the seller's banking destination to ensure that everything adds up. There are two steps in the reconciliation process: comparing the deposit amount from the bank statement to the payout amount and identifying which transactions go into each payout.
The Payouts API doesn’t include data that's older than January 2021. To access this historical data, use the Seller Dashboard.
The Payout object shows the sum of all transactions paid to a seller's banking destination. It's a parent to a set of child payout entries that reflect the balance change for each transaction.
Each Payout object has an id field, which uniquely identifies the Payout object for your application. It also has an end_to_end_id field that might appear on the seller's bank statements.
Note
You can use the end_to_end_id field to automate the process of reconciling each payout with the corresponding line item on the seller's bank statement.
The version field is initially set to 0. For each successful update, Square increases the version number. You can use the version field for optimistic concurrency.
{
"payout": {
"id": "po_070431e4-e351-11eb-a8bb-02420a140009",
"status": "SENT",
"location_id": "{LOCATION_ID}",
"created_at": "2021-07-12T20:37:51Z",
"updated_at": "2021-07-12T20: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",
"end_to_end_id": "L2100000000"
}
}The following table describes a few of the key fields:
| Field | Description | |
|---|---|---|
amount_money | The amount and currency of the payout that is either sent to or pulled from the seller's banking destination. A positive value for the amount_money field represents a credit and increases the balance of the seller's banking destination. A negative value for the amount_money field represents a debit and decreases the balance of the seller's banking destination. | |
created_at | The timestamp of when the payout is sent to the banking destination. | |
arrival_date | The timestamp of when the seller can expect the funds to arrive in or be taken out of the banking destination (in ISO 8601 local date format). | |
destination | The type and ID, where applicable, of the bank to which the payout is made. The following destination types are supported:
| |
type | The type of payout include the following:
| |
| A unique ID for the payout that might appear on the seller's bank statement. The following guidelines apply to the
|
A Payout object can have one of three states: SENT, PAID, or FAILED.
The initial status of a payout is SENT. If Square doesn't receive any response from the seller's bank for a time period, Square assumes that the payout is successfully deposited and updates the status to PAID.
If the seller's bank account sends a response saying that the payout failed, Square updates the status of the payout entry to FAILED.
If the response from the seller's bank comes back later than Square expects, a payout that is initially marked as PAID can transition to FAILED because the deposit or withdrawal ultimately failed.
Note
You can use webhooks in an application to constantly listen for a state change in the payouts data and notify you when it meets certain conditions. For example, you might use a webhook to set up an email alert for when a payout state changes from PAID to FAILED. For more information about using webhooks, see Square Webhooks Overview.
Consider a scenario where a seller runs several coffee shops across the country. The coffee shops process thousands of card payments per week.
The seller has set up an automated payout schedule, whereby at the end of each day Square sends a payout to the seller's bank account.
You might use the Payouts API to review the summary of all payouts to make sure it matches with the seller's bank account balance.