Payouts API

Applies to: Payouts API

Use the Payouts API to 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 Square Dashboard.

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.

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.

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:

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.

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

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.

# Sample Python code for automated accounting reconciliation
from square.http.auth.o_auth_2 import BearerAuthCredentials
from square.client import Client
import os

# Set the access token from environment variable
SQUARE_ACCESS_TOKEN = os.environ['SQUARE_ACCESS_TOKEN']

# Set the location ID
location_id = 'YOUR_LOCATION_ID'

# Get Payouts API client
payouts_api = Client(
       bearer_auth_credentials=BearerAuthCredentials(
           access_token=SQUARE_ACCESS_TOKEN
       ),
       environment='sandbox').payouts

result = payouts_api.list_payouts(location_id = location_id)
if result.is_success():
   payouts = result.body.get('payouts', [])
   for payout in payouts:
       print("Payout ID:", payout['id'], "Amount:", payout['amount_money']['amount'])
elif result.is_error():
   print("Error retrieving payouts: ", result.errors)

# Sample Python code for getting a payout of a merchant
from square.http.auth.o_auth_2 import BearerAuthCredentials
from square.client import Client
import os

# Set the access token from environment variable
SQUARE_ACCESS_TOKEN = os.environ['SQUARE_ACCESS_TOKEN']

# Get Payouts API client
payouts_api = Client(
       bearer_auth_credentials=BearerAuthCredentials(
           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)

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.

# 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)

# Sample Python code for getting list of event types supported in webhook subscription
from square.http.auth.o_auth_2 import BearerAuthCredentials
from square.client import Client
import os

# Set the access token from environment variable
SQUARE_ACCESS_TOKEN = os.environ['SQUARE_ACCESS_TOKEN']

# Set the location ID
location_id = 'YOUR_LOCATION_ID'

# Get webhook subscriptions api client
webhook_subscriptions_api = Client(access_token=SQUARE_ACCESS_TOKEN, environment='sandbox').webhook_subscriptions

result = webhook_subscriptions_api.list_webhook_event_types()
if result.is_success():
    print("======== Currently supported event types ========")
    for event_type in result.body.get('event_types'):
        print(event_type)
    print("======== Event type metadatas ========")
    for event_metadata in result.body.get('metadata'):
        print(f"{event_metadata.get('event_type')} | Api version introduced: {event_metadata.get('api_version_introduced')} | Release status: {event_metadata.get('release_status')}")

# Specifically for payout, there are three event types we currently support:  "payout.failed", "payout.paid", "payout.sent", but use list_webhook_event_types() whenever you want to subscribe to new event types