Payouts API Overview

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.

Link to section

Example use case

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 Square sends a payout to the seller's bank account at the end of each day.

You might use the Payouts API to review the summary of all payouts to make sure it matches the seller's bank account balance.

You can also have the following use cases:

  • Processing fees - Compute processing fees for a payout by iterating through all payout entries. For example, if a payout has four entries: one charge for $100 with a $2 fee, one loan repayment for –$10, one refund for –$50 with a $1 fee, and a loan repayment refund for –$5, the total processing fee amount for this payout is $1. This is calculated as $2 + $0 – $1 + $0.
  • Online marketplace - An online marketplace app uses the Payouts API to see a list of deposits and withdrawals from a seller's banking destination. This could involve multiple sellers simultaneously reconciling their transactions.
  • Subscription services - A subscription-based service uses the Payouts API to reconcile regular payments to content creators.
  • Retail refunds - A retail business uses the Payouts API to track refunds for customers. This could involve the partial or full refund of purchases made in-store or online.
  • Service marketplace - A service marketplace, such as a home services platform, uses the Payouts API to track payments to service providers after they complete jobs.
Link to section

Payout object

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.

The following table describes a few of the key fields:

FieldDescription
amount_moneyThe 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_atThe timestamp of when the payout is sent to the banking destination.
arrival_dateThe 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).
destinationThe type and ID, where applicable, of the bank to which the payout is made. The following destination types are supported:
  • BANK_ACCOUNT - An external bank outside of Square.
  • CARD - A debit card for the transfer. This is only applicable for manual transfers.
  • SQUARE_STORED_BALANCE - A Square checking or savings account in the United States.
typeThe type of payout include the following:
  • BATCH - Payouts that include a list of payout entries that can be considered settled.
  • SIMPLE - Arbitrary amount payouts that don't have any payout entries associated with them. However, a corresponding payout entry is created in the subsequent batch payout to deduct the amount of the simple payout.

end_to_end_id

A unique ID for the payout that might appear on the seller's bank statement. The following guidelines apply to the end_to_end_id field:

  • Automatic transfer setting - The seller must enable the automatic transfer setting for the end_to_end_id field to appear.

  • Manual transfers - The end_to_end_id field isn't supported for manual transfers.

  • Instant transfers - The end_to_end_id field is supported for instant transfers only if the seller has enabled automatic transfers.

  • International banks - Banks located in non-US regions might not include the end_to_end_id field on their bank statements.

Link to section

Payout states

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.

payout-api-states

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.

Link to section

Real-world use cases

This section describes a few practical applications for using the Payouts API.

Note

Square access tokens are required to authenticate and authorize API requests. The samples in this section assume that your access token resides in an environment file in your project folder. If you're executing a sample as a standalone Python script, replace os.environ['SQUARE_ACCESS_TOKEN'] with your access token. You can find your Sandbox access token in the Developer Dashboard.

Link to section

Reconciling transactions

You can use the Payouts API to develop an application to automatically reconcile transactions to and from the Square seller's banking destination. Automating accounting reconciliation streamlines financial processes, reduces manual effort, and minimizes the risk of errors in maintaining accurate financial records.

You need to create your own reconciliation logic based on the payout data received from the API. This reconciliation logic is essential for aligning transactions with payouts and ensuring accurate accounting records.

The following code retrieves the payouts for a specific Square location and prints their IDs and amounts. You can use this data as a starting point for creating your own reconciliation logic based on the specific needs of your accounting system.

In this code sample, you must set the following parameter:

  • Location ID - Set the location_id to specify the Square location for which the payouts are being retrieved. You can access location IDs through the Locations API or from the Locations tab in the Developer Dashboard.

The code does the following:

  • Payouts retrieval - The code invokes the list_payouts method of the Payouts API to fetch a list of payouts linked to the specified location.
  • Iterating through payouts - A loop iterates through the retrieved payouts. For each payout, you can implement your custom reconciliation logic.

The code outputs the following for each payout in the list:

  • Payout ID - The unique identifier for the payout.
  • Amount - The amount of the payout.

In the payout object, you also have access to the following:

  • Currency code - The currency code of the payout.
  • Status - The current status of the payout. For example, SENT, PAID, or FAILED. For information see Payout states.
  • Arrival date - The expected arrival date of the funds in the bank account.
Link to section

Get the end_to_end_id field of a payout

The end_to_end_id field is a unique ID for the payout that might appear on the seller's bank statement. You can use this field to uniquely identify a Payout object for your application and match it with your bank statement. Banks located in non-US regions might not include the end_to_end_id field on their bank statements.

# Sample Python code for getting a payout of a seller from square.client import Client import os, json # Set the access token from environment variable SQUARE_ACCESS_TOKEN = os.environ['SQUARE_ACCESS_TOKEN'] # Get payouts api client payouts_api = Client(access_token=SQUARE_ACCESS_TOKEN, environment='sandbox').payouts payout_id = 'payout_id' result = payout_api.get_payout(payout_id) if result.is_success(): print(json.dumps(result.body, indent=4)) elif result.is_error(): print(f"Error retrieving payout with id {payout_id}: ", result.errors)

In the code sample, you must set the following parameter:

  • Payout ID - Set the payout_id to specify the payout for which you want to retrieve the end_to_end_id field along with other information.
Link to section

Real-time payout status monitoring (webhook handling)

You can use webhooks to listen for state changes in payout data, enabling real-time notifications when a payout's state changes (for example, from PAID to FAILED), allowing for prompt actions and alerts. For more information, see Payout states.

Link to section

setup.py

# Sample Python code for webhook handling from flask import Flask, request app = Flask(__name__) @app.route('/webhook', methods=['POST']) def webhook_listener(): data = request.get_json() # Implement logic to handle payout state changes print("Webhook Received - Payout State Change:", data['event']['type']) return 'Webhook Received', 200 if __name__ == '__main__': app.run(port=5000)

The setup.py script does the following:

  • Flask application setup - Creates a Flask application and defines an endpoint (/webhook) to handle incoming webhook events.
  • Webhook event processing - The webhook_listener function runs when a POST request is received at the /webhook endpoint. It does the following:
    • Extracts JSON data from the request, representing the webhook event.
    • Contains logic to handle payout state changes. This sample prints a message indicating the type of payout event received.
    • Sends a response with the message 'Webhook Received' and a 200 status code to acknowledge the receipt of the webhook event.
Link to section

list_webhook_events.py

The list_webhook_events.py script retrieves the available event types supported in the payout webhook. For more information, see Webhook Subscriptions API Overview.