Payouts

Applies to: Payouts API

Cash App Payouts (CAP) allow merchants to send funds directly to customers’ Cash App accounts.

How it Works

Payouts are always immediately captured and processed asynchronously.

Two actions are required to process a payout:

1. Customer request and grant: the customer approves an ON_FILE_PAYOUT grant, authorizing the merchant to send funds to their Cash App account.
2. Payout creation: the partner creates the payout against that grant. Authorization and capture happen together in a single step, and the funds are credited to the customer’s Cash App account.

Fees

Payout fees (if applicable) are added to the amount Cash App pulls from the partner. The fee structure is configured per partner and may include both fixed and variable components:

• Variable Fee: A percentage of the payout amount (basis points)
• Fixed Fee: A flat fee per payout

The total cost to the partner is: payout_amount + fee_variable + fee_fixed

Customer Notifications

When a payout is successfully captured, the customer receives notifications through multiple channels:

• Push notification
• Activity feed entry in the Cash App
• Email (if configured)

These notifications include information about the payout amount, merchant name, and purpose.

Payout Funding

Cash App funds payouts by pulling funds from the partner’s registered bank account. Partners do not send funds to Block — no action is required from you at funding time beyond keeping the account funded and available for Cash App to pull from.

Funding Process

1. Bank Account Registration: The partner provides the details of the bank account to be pulled from, and Block’s Technical Account Manager (TAM) registers it for payout funding. Cash App pulls payout settlement funds only from the registered account.

2. Pre-Integration Verification: Before enabling the integration, Block verifies the registered account and confirms that Cash App can pull funds from it. Payouts cannot be enabled until the account is active and available to pull from.

3. Daily Pull: Cash App initiates a single pull per settlement batch, covering the total for that batch — not a separate pull for each payout. The pull occurs the business day after the batch is generated. The Payout Summary Report details the total amount Cash App will pull for that batch.

4. Account Consistency: Cash App pulls only from the registered account. If the partner needs to change the funding account, coordinate the change with your TAM in advance.

Cutoff Time and Business Days

Captured payouts are grouped into a settlement batch at a designated cutoff time (default 23:00 UTC). A batch spans the previous cutoff to the current one. See Payout Settlements for the full batching and reporting details.

• A payout captured before the cutoff is included in that day’s batch and pulled the next business day.
• A payout captured after the cutoff rolls into the next batch and is pulled the business day after that batch is generated.

Batching and pulls follow the Federal Reserve calendar — they do not occur on Saturdays, Sundays, or U.S. federal holidays. If the day after a batch is not a business day, the pull occurs on the next business day.

Funding Timeline

The funding timeline follows this sequence:

• Day 1: Payouts are captured before the cutoff time and included in that day’s settlement batch.
• Day 1, after cutoff: The settlement batch closes and the Payout Summary Report is generated, showing the total amount to be pulled.
• Next business day: Cash App pulls the batch total from the partner’s registered bank account in a single pull.

Payout Operations

Use the Payouts API to perform the following operations:

• GET: List payouts
  Returns a list of payouts matching the given query parameters. Rate limited to 100 QPS.
• POST: Create payout
  Creates a payout to a customer. A payout allows a partner to send money to a customer’s Cash App account on behalf of one of its merchants.
• GET: Retrieve payout
  Retrieves a payout by its ID.

Payout States

Payouts support the following states:

Step 1: Customer Request and Grant

Before initiating a payout, merchants must obtain explicit authorization from the customer. To do this, create a customer request that prompts the user for approval. Once approved, Cash App generates a payout grant, which serves as your authorization to disburse funds directly to the customer’s Cash App account.

Action Type

Payouts require an ON_FILE_PAYOUT grant action type:

cURL Example

>curl --request POST \
     --url https://sandbox.api.cash.app/customer-request/v1/requests \
     --header 'Authorization: Client api_key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
    "idempotency_key": "random_uuid",
    "request": {
        "actions": [
            {
                "type": "ON_FILE_PAYOUT",
                "account_reference_id": "account_ref_id",
                "scope_id": "brand_id"
            }
        ],
        "channel": "ONLINE"
    }
}
'

Grant Validation Failure Scenarios and Codes

Step 2: Payout Creation

Payouts are always immediately captured (auth and capture happen together). Unlike payments, payouts do not support a separate authorization and capture flow.

Payout Process

When a payout is created:

1. The request is validated (amount, currency, merchant, and grant).
2. The customer’s Cash App account is verified and the payout is authorized.
3. The payout is automatically captured and funds are credited to the customer’s account.
4. Settlement reconciliation records are created for partner reporting.
5. The customer receives a notification about the payout.

Request Validation

Before authorization, the following validations are performed:

• Amount Validation: Payout amount must be positive (greater than $0.00).
• Capture Mode: Only immediate capture is currently supported (capture: true).
• Idempotency: Each request must include a unique idempotency key. If a request is retried with the same key and identical parameters, the original payout result is returned.
• Grant Validation: The grant must be valid, not expired, not revoked, and have the correct action type (ON_FILE_PAYOUT).
• Merchant Validation: The merchant must exist, be active, and have completed onboarding.

cURL Example

>curl --request POST \
     --url https://sandbox.api.cash.app/network/v1/payouts \
     --header "Authorization: Client client_id api_key \
     --header 'X-Region: PDX' \
     --header 'X-Signature: sandbox:skip-signature-check' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
    "idempotency_key": "random_uuid",
    "payout": {
        "amount": 1500,
        "currency": "USD",
        "merchant_id": "merchant_id",
        "grant_id": "GRG_sandbox:active",
        "purpose": "SERVICES",
        "capture": true,
        "note": "Payment for consulting services"
    }
}
'

Example response

{
    "payout": {
        "payout_id": "CAPO_4nn21zy6t0v2yhqg5bvhk7xkq",
        "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50",
        "amount": 1500,
        "currency": "USD",
        "customer_id": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
        "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
        "purpose": "SERVICES",
        "note": "Payment for consulting services",
        "status": "CAPTURED",
        "created_at": "2022-01-01T12:00:00Z",
        "updated_at": "2022-01-01T12:00:05Z"
    }
}

Payout Creation Failure Scenarios and Codes