Technical GuidesPayouts

Payout Settlements

Payout settlements represent amounts that partners owe Cash App for transactions processed through the platform. Cash App pulls these amounts from the partner’s registered bank account — the settlement reports tell you what has been or will be pulled.

Payouts are only supported for Cash App Pay PSP partners. Payout settlement is always between Cash App and the partner, per client_id, even though individual transactions in the reports are attributed to a merchant_id.

How it Works

Cash App will process payout settlements for all eligible transactions before a 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 partners 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 partner.

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

  • SFTP hostname
  • SFTP port
  • Username of the partner’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.
payout_idStringCash App identifier for the associated payout.
payout_reference_idStringClient-provided reference ID specified on the payout.
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 partner 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 (partner pays fee, e.g., -$5) or Zero
  • netAmount: Negative (total partner owes, e.g., -$505)
  • netAmount = grossAmount + feeAmount** (e.g., -500 + -5 = -505)

CSV Sample

merchant_id,merchant_reference_id,payout_id,payout_reference_id,settlement_batch_id,transaction_time,net_amount,gross_amount,fee_amount,fee_variable,fee_fixed,currency_code
MMI_9w89nidchumz9ktrcpnalg2ny,merchant_ref_123,CAPO_4nn21zy6t0v2yhqg5bvhk7xkq,payout_ref_123,PWCS_fg2sxvvhg1ff9p4tj1731sdy3,2021-01-02T10:24:21Z,-10300,-10000,-300,-100,-200,USD
MMI_9w89nidchumz9ktrcpnalg2ny,merchant_ref_123,CAPO_8j9k2lm3n4op5q6r7st8uv9wx,payout_ref_456,PWCS_fg2sxvvhg1ff9p4tj1731sdy3,2021-01-02T11:15:32Z,-5250,-5000,-250,-75,-175,USD
MMI_9w89nidchumz9ktrcpnalg2ny,merchant_ref_123,CAPO_1a2b3c4d5e6f7g8h9i0j1k2lm,payout_ref_789,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 Cash App will pull from the partner’s registered bank account 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 partner owes and what Cash App will pull. This is a negative value.
settlement_batch_idStringCash App identifier of the settlement batch.

CSV Sample

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