Payouts API

Applies to: Payouts API

Learn how the Square API represents payouts.

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.

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.

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.

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.

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.

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.

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

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.

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

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.

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.