Technical GuidesPayouts

Payout Settlements

Early Access

Payouts is an early access feature. We’re actively improving this API based on your feedback.

Early access features come with some caveats:

  • May evolve rapidly, requiring integration updates
  • Not subject to our 10 year version support policy
  • Not subject to SLAs (unless specified in a contract)

Payout settlements represent amounts that merchants owe to Cash App for transactions processed through the platform. Merchants push funds to Block based on these settlement reports.

How it Works

Cash App will process payout settlements for all eligible transactions before a configurable designated cutoff time. The settlement process follows the Federal Reserve calendar for availability, meaning that settlements are not available on Saturdays, Sundays, and holidays.

Payout settlements for transactions captured prior to the configured cutoff time will be initiated the same business day, subject to U.S. federal holidays.

Batch Processing

Cash App processes payout settlements for merchants via a batch process. We capture the transaction-level details of each payout settlement as reconciliation reports and upload them to a client-provided SFTP server.

For each daily batch of payout transactions that must be settled, Cash App generates a settlement batch. Each settlement includes a series of associated reconciliation reports that can contain up to 9,999 transactions per report.

Settlement Configuration

PropertyTypeDescription
Settlement TimeString
The time in a 24-hour clock (hh:mm) in UTC (ISO 8601-1:2019)		The cutoff time for settling any unsettled eligible payout transactions. The batch will span the previous cutoff (on a business day) to the current one. Default: 23:00

Reconciliation Reports

Each payout settlement has a corresponding reconciliation report showing the details of each transaction, including amounts and fees used in the calculation of the settlement amount. These reports are delivered daily using Secure File Transfer Protocol (SFTP) to the PSP.

To upload reconciliation reports to the SFTP server, we need the following information:

  • SFTP hostname
  • SFTP port
  • Username of the PSP’s SFTP server
  • SFTP user’s private RSA key
  • SFTP server host’s public RSA key (optional)
  • Destination folder path (filepath for uploading the reports)
Reports are in CSV format and use a UTF-8 encoding.

As an additional security benefit, Cash App Pay can optionally PGP encrypt settlement files before they’re uploaded to the client SFTP server.

Payout Settlement Report

To avoid upload collisions, each payout settlement report has a unique filename using the following convention: <yyyymmdd>_payout_settlement_report_client_<client-id>_batch_<batch-id>_chunk_<chunk index>.csv

For sandbox environments, the filename follows this pattern: <yyyymmdd>_sandbox_payout_settlement_report_client_<client-id>_batch_<batch-id>_chunk_<chunk index>.csv

<yyyymmdd> is the date of settlement for the settlement batch. For manually generated payout settlement reports, <yyyymmdd> is the date the report was generated.

CSV Schema

Payout settlement report files can contain up to 9,999 records. Each file contains headers in the top row, and then each subsequent row has the following schema:

Column NameTypeDescription
merchant_idStringCash App identifier for the associated merchant.
merchant_reference_idStringClient-provided reference ID specified on the merchant.
settlement_batch_idStringCash App identifier of the batch of transactions this transaction was settled with.
transaction_timeString(datetime using RFC 3339 standard in UTC)The time at which the transaction event occurred.
net_amountNumber (Integer)The net amount (after fees) for this transaction representing the total amount the merchant owes.
gross_amountNumber (Integer)The gross amount of this transaction. This is the base transaction amount before fees.
fee_amountNumber (Integer)The total fee associated with this transaction.
fee_variableNumber (Integer)The variable fee component associated with this transaction.
fee_fixedNumber (Integer)The fixed fee component associated with this transaction.
currency_codeString (ISO 4217 Alpha-3 Currency code)Client’s configured currency. Amounts use the smallest-denomination unit available in this currency. (for example, amount = 100 for $1 USD, where the smallest unit is a cent)

Amount Convention

The amounts in payout settlement reports follow this convention:

  • grossAmount: Negative (represents payout amount sent, e.g., -$500)
  • feeAmount: Negative (merchant pays fee, e.g., -$5) or Zero
  • netAmount: Negative (total merchant owes, e.g., -$505)
  • netAmount = grossAmount + feeAmount** (e.g., -500 + -5 = -505)

CSV Sample

1merchant_id,merchant_reference_id,settlement_batch_id,transaction_time,net_amount,gross_amount,fee_amount,fee_variable,fee_fixed,currency_code
2MMI_9w89nidchumz9ktrcpnalg2ny,merchant_ref_123,PWCS_fg2sxvvhg1ff9p4tj1731sdy3,2021-01-02T10:24:21Z,-10300,-10000,-300,-100,-200,USD
3MMI_9w89nidchumz9ktrcpnalg2ny,merchant_ref_123,PWCS_fg2sxvvhg1ff9p4tj1731sdy3,2021-01-02T11:15:32Z,-5250,-5000,-250,-75,-175,USD
4MMI_9w89nidchumz9ktrcpnalg2ny,merchant_ref_123,PWCS_fg2sxvvhg1ff9p4tj1731sdy3,2021-01-02T14:45:18Z,-2060,-2000,-60,-20,-40,USD

Payout Summary Report

The payout summary report provides the total amount of payouts sent for a given day, not a running balance. It shows the total amount due for a specific settlement batch.

To avoid upload collisions, each report has a unique filename using the following convention: <yyyymmdd>_payout_summary_report_client_<client-id>_batch_<batch-id>.csv

For sandbox environments, the filename follows this pattern: <yyyymmdd>_sandbox_payout_summary_report_client_<client-id>_batch_<batch-id>.csv

<yyyymmdd> is the date of settlement for the settlement batch.

CSV Schema

Each file contains headers in the top row, and then a single row with the following schema:

Column NameTypeDescription
categoryStringThe record category (always amount_due for payout settlements)
descriptionStringDescription of the record (format: Amount Due (YYYY-MM-DD), where the date is the settlement date)
currencyString (ISO 4217 Alpha-3 Currency code)Client’s configured currency. Amounts use the smallest-denomination unit available in this currency. (For example, amount = 100 for $1 USD, where the smallest unit is a cent.)
net_amountNumber(Integer)Total net amount due for this settlement batch, representing what the merchant owes. This is a negative value.
settlement_batch_idStringCash App identifier of the settlement batch.

CSV Sample

1category,description,currency,net_amount,settlement_batch_id
2amount_due,Amount Due (2021-01-02),USD,-17610,PWCS_fg2sxvvhg1ff9p4tj1731sdy3