Payouts API

Learn how the Square API represents payouts.

Overview

A payout is a transfer of funds from a seller's Square account to another banking destination, most often the seller’s external bank account.

In the United States, a typical payout includes transactions made after 5PM PST on one business day and before 5PM PST on the next business day. In Australia, Japan, and the United Kingdom, the cutoff is 12AM local time. Due to this payout schedule, there can be a discrepancy between the orders that a seller processes on a given business day, reflected in their Square Dashboard balance and the funds in their bank account.

A payout generates a Payout object and corresponding PayoutEntry objects:

Payout summarizes a transfer of funds. Calls to ListPayouts and GetPayout return Payout objects.
PayoutEntry lists each transaction included in a Payout. Calls to ListPayoutEntries return PayoutEntry objects.

With the Payouts API, you can reconcile a seller's Square Dashboard balance to their bank account balance. You can also combine calls to the Payouts API with requests to the Payments API and Orders API to model the seller’s Square balance in your application.

Note

The Payouts API doesn’t include data that's older than January 2021. To access this historical data, use the Square Dashboard.

Link to section

How the Payouts API works

Link to section

Payout object

Calls to ListPayouts and GetPayout return Payout objects. A Payout object represents a payout, which is the sum of all transactions included in a transfer of funds from a seller’s Square account to an external banking destination.

The following example Payout represents a transfer of $97.10 from a seller’s Square account to their bank account:

{
  "payout": {
    "id": "po_1234567890abcdef",
    "status": "PAID",
    "location_id": "loc_0987654321fedcba",
    "created_at": "2024-12-04T00:09:10Z",
    "updated_at": "2024-12-04T00:09:10Z",
    "amount_money": {
      "amount": 9710,
      "currency_code": "USD"
    },
    "destination": {
      "type": "BANK_ACCOUNT",
      "id": "bact_abcdef1234567890"
    },
    "version": 1,
    "type": "BATCH",
    "arrival_date": "2024-12-04",
    "end_to_end_id": "e2e_1234abcd5678efgh"
  }
}

The following list describes some of the key Payout response fields. For a comprehensive definition of the object that details each field, see Payout in the API Reference.

id - A unique identifier for the payout. Pass an id in a request to ListPayoutEntries to look up the transactions included in the payout. Each transaction is represented as a PayoutEntry.
status - The state of the Payout are:
- SENT - The initial status of the payout.
- PAID - The payout is successfully deposited.
- FAILED - The seller's bank notified Square that the payout failed. A payout that's initially marked as PAID can transition to FAILED if the response from the seller's bank comes back later than Square expects.
Note
You can set up webhooks to notify you of payout state changes. 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.
created_at - The timestamp of when the payout is sent to the banking destination.
amount_money - The amount and currency of the payout that's either sent to or pulled from the seller's banking destination. A positive value for the amount_money field represents a credit that 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.
destination - The type and ID, where applicable, of the banking destination to which the payout is made. If the amount_money field is negative, the funds reflected in this Payout were deducted from the destination.
version - The version number, which starts at 0 and is incremented each time an update is made to the payout record. You can use the version field for optimistic concurrency.
type - The type of payout: BATCH or SIMPLE. A BATCH payout is a transfer of a seller's entire Square balance. Most payouts are BATCH payouts. A SIMPLE payout is a transfer of any amount less than the entire balance.
end_to_end_id - A unique ID for the payout that might appear on the seller's bank statement, if the seller is based in the United States. The seller must enable the automatic transfer setting for the end_to_end_id field to appear.

Link to section

PayoutEntry object

Calls to ListPayoutEntries return PayoutEntry objects. A PayoutEntry represents one or more transactions included in a payout.

The following PayoutEntry corresponds to the previous $97.10 example Payout. The payout_entries array includes two objects that represent a credit card charge of $150 and a refund of $50, respectively. After fees, the final amount transferred to the seller's bank account is $97.10.

{
  "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"
      }
    }
  ]
}

For detailed descriptions of each response field, see PayoutEntry in the API Reference.

Link to section

Advanced payout types

Link to section

Cost Plus

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.

Important

When reconciling transactions for a Cost Plus seller, you need to account for estimated versus final transactions.

For example, Square charges an initial estimated $1 fee for a transaction. One of the payout_entries for the next day's Payout represents the transaction and accounts for the fee, as shown in the following example:

{
  "payout_entries": [
    {
      "id": "poe_1a2b3c4d5e6f7g8h9i0j",
      "payout_id": "po_4d28e6c4-7dd5-4de4-8ec9-a059277646a6",
      "effective_at": "2022-03-24T03:07:09Z",
      "type": "CHARGE",
      "gross_amount_money": {
        "amount": 3462,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 100,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": 3362,
        "currency_code": "USD"
      },
      "type_charge_details": {
        "payment_id": "JkL9M8N7O6P5Q4R3S2T1U0V9W8X7Y6Z5"
      }
    }
  ]
}

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 in a reconciliation Payout. This reconciliation Payout includes all the Cost Plus adjustments for the month as distinct payout entries. Each PayoutEntry has a type of FEE.

The example $0.25 PayoutEntry for the Cost Plus reconciliation 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 same payment_id attached to the PayoutEntry for the original CHARGE.

Link to section

Gross Settlement

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.

Important

When reconciling transactions for a Gross Settlement seller, you need to account for the monthly lump sum debit.

For example, a seller processes a $34.62 transaction. Square doesn't charge a fee. One of the payout entries for the next day’s Payout represents the transaction. The fee_amount_money value is 0, as shown in the following example:

{
  "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"
      }
    }
  ]
}

At the end of the month, Square charges a $0.75 fee for the transaction. Square debits $0.75 from the seller as part of the reconciliation Payout. This reconciliation Payout includes all the transaction fees for the month as distinct payout entries. Each 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_1234567890abcdef",
      "payout_id": "po_0987654321fedcba",
      "effective_at": "2022-03-24T03:07:09Z",
      "type": "PROCESSING_FEE",
      "gross_amount_money": {
        "amount": -75,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 0,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": -75,
        "currency_code": "USD"
      }
    }
  ]
}

Important

Any time that you sync a PayoutEntry type of FEE or PROCESSING_FEE, the gross_amount_money value is an update to a previous fee.

Link to section

Instant Deposit

Note

Instant Deposit is currently available in the US, the UK, Canada, and Australia.

With Instant Deposit, a seller can deposit their funds to a linked bank account or debit card within seconds. A seller triggers an Instant Deposit from the Square Dashboard or Square Point of Sale.

Square charges a service fee for Instant Deposit. An Instant Deposit generates a Payout object and an associated PayoutEntry with a type of DEPOSIT_FEE.

Warning

If the Instant Deposit is transferred to a card, a payout.payout_fee is also returned. An Instant Deposit transferred to bank accounts doesn't return this field. For consistency, always use PayoutEntry instead of payout.payout_fee to calculate fees.

The following example Instant Deposit Payout represents a transfer of $70.73 from a seller's Square account to their card. Square charges a $1.26 fee for the transfer, as reflected in payout.payout_fee.

{
  "payout": {
    "id": "po_6542107a-323c-6a93-b9df-cggg3949b7e",
    "status": "PAID",
    "location_id": "XZKT883AFFSS4E",
    "created_at": "2025-01-23T22:04:59Z",
    "updated_at": "2025-01-23T23:09:09.684Z",
    "amount_money": {
      "amount": 7073,
      "currency_code": "USD"
    },
    "destination": {
      "type": "CARD",
      "id": "ccof:e3se0xPa3TF7tOe03GB"
    },
    "version": 2,
    "type": "BATCH",
    "payout_fee": [
      {
        "amount_money": {
          "amount": 126,
          "currency_code": "USD"
        },
        "effective_at": "2025-01-23T22:04:59Z",
        "type": "TRANSFER_FEE"
      }
    ],
    "arrival_date": "2025-01-23",
    "number_of_entries": 4,
    "end_to_end_id": "613485392229"
  }
}

A call to ListPayoutEntries returns the following PayoutEntry objects for the example Payout. In this case, there are three CHARGE entries. The sum of their net_amount values totals $71.79. Subtracting the one DEPOSIT_FEE net_amount of $1.26, the total value transferred in the payout to the card is $70.73.

{
  "payout_entries": [
    {
      "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"
      }
    },
    {
      "id": "poe_Akd_9DYNNA8DBxj9sG8QACRpHx1",
      "payout_id": "po_6542107a-323c-6a93-b9df-cggg3949b7e",
      "effective_at": "2025-01-23T21:06:16Z",
      "type": "CHARGE",
      "gross_amount_money": {
        "amount": 2996,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 88,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": 2908,
        "currency_code": "USD"
      },
      "type_charge_details": {
        "payment_id": "TVkjM7i1BXWSwQwp7ZVxZyQjwJCZY"
      }
    },
    {
      "id": "poe_QJUQa8cew6DFyQ3yixbympU_u8F",
      "payout_id": "po_6542107a-323c-6a93-b9df-cggg3949b7e",
      "effective_at": "2025-01-23T20:08:01Z",
      "type": "CHARGE",
      "gross_amount_money": {
        "amount": 2140,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 66,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": 2074,
        "currency_code": "USD"
      },
      "type_charge_details": {
        "payment_id": "bXbR15tELfb6ChVeh5A0Ye6EvTAZY"
      }
    },
    {
      "id": "poe_9lnaZeIyJFQKzRanQRSsxLHAbr9",
      "payout_id": "po_6542107a-323c-6a93-b9df-cggg3949b7e",
      "effective_at": "2025-01-23T18:39:48Z",
      "type": "CHARGE",
      "gross_amount_money": {
        "amount": 2286,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 69,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": 2217,
        "currency_code": "USD"
      },
      "type_charge_details": {
        "payment_id": "vHAg6urZptF4FVmX78MxRKgaWfJZY"
      }
    }
  ]
}

Link to section

Scheduled Deposit

A Scheduled Deposit is an Instant Deposit that a seller schedules to occur at their close of business on a specific day of the week. A Scheduled Deposit Payout has an associated PayoutEntry with a type of DEPOSIT_FEE, like the previous example for an Instant Deposit.

Link to section

Payouts API operations

You can execute the following operations with the Payouts API:

ListPayouts - Retrieve a list of payouts for a provided location ID.
GetPayout - Retrieve details about a specific payout.
ListPayoutEntries - Retrieve a list of all the payout entries associated with a provided payout ID.

Docs

Payouts API

On this page

Overview

Note

How the Payouts API works

Payout object

Note

PayoutEntry object

Advanced payout types

Cost Plus

Important

Gross Settlement

Important

Important

Instant Deposit

Note

Warning

Scheduled Deposit

Payouts API operations

On this page