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
2. Payout creation (authorization and capture)

Fees

Payout fees (if applicable) are added to the amount deducted from the merchant’s settlement balance. The fee structure is configured per merchant 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 merchant 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

Merchants fund payouts by pushing funds directly to Block.

Funding Process

1. Account Details Provisioning: Block’s Technical Account Manager (TAM) will share the account details where merchants should send funds.

2. Pre-Integration Verification: Before enabling the integration, merchants must send a $0.01 test deposit to verify that the funding account details are correct and the transfer mechanism is properly configured.

3. Daily Funding: Merchants are expected to send payment the day after the Payout Summary Report is generated. This report details the total amount of payouts sent for that day.

4. Payment Rails Consistency: Merchants must use the same payment rails and source accounts that were configured and verified during the pre-integration verification. Payments from unconfigured accounts will not be accepted.

Funding Timeline

The funding timeline follows this sequence:

• Day 1: Payouts are processed and captured.
• Day 1 EOD: Payout Summary Report is generated showing the total amount due.
• Day 2: Merchant pushes funds to Block based on the report amount.

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 merchant to send money to a customer’s Cash App account.
• GET: Retrieve payout
  Retrieves a payout by its ID.

Payout States

Payouts support the following states:

Step 1: Customer Request and Grant

To get permission to send a payout to a customer, a M/PSP must obtain a grant after receiving a customer request. A grant represents a customer’s approval for a merchant to send funds to their Cash App account.

After a grant is obtained, a M/PSP can create payouts on behalf of the customer.

Action Type

Payouts require an ON_FILE_PAYOUT grant action type:

cURL Example

1
>curl --request POST \
2
     --url https://sandbox.api.cash.app/customer-request/v1/requests \
3
     --header 'Authorization: Client api_key' \
4
     --header 'accept: application/json' \
5
     --header 'content-type: application/json' \
6
     --data '
7
{
8
    "idempotency_key": "random_uuid",
9
    "request": {
10
        "actions": [
11
            {
12
                "type": "ON_FILE_PAYOUT",
13
                "account_reference_id": "account_ref_id",
14
                "scope_id": "brand_id"
15
            }
16
        ],
17
        "channel": "ONLINE"
18
    }
19
}
20
'

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 merchant 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

1
>curl --request POST \
2
     --url https://sandbox.api.cash.app/network/v1/payouts \
3
     --header "Authorization: Client client_id api_key \
4
     --header 'X-Region: PDX' \
5
     --header 'X-Signature: sandbox:skip-signature-check' \
6
     --header 'accept: application/json' \
7
     --header 'content-type: application/json' \
8
     --data '
9
{
10
    "idempotency_key": "random_uuid",
11
    "payout": {
12
        "amount": 1500,
13
        "currency": "USD",
14
        "merchant_id": "merchant_id",
15
        "grant_id": "GRG_sandbox:active",
16
        "purpose": "SERVICES",
17
        "capture": true,
18
        "note": "Payment for consulting services"
19
    }
20
}
21
'

Example response

1
{
2
    "payout": {
3
        "payout_id": "CAPO_4nn21zy6t0v2yhqg5bvhk7xkq",
4
        "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50",
5
        "amount": 1500,
6
        "currency": "USD",
7
        "customer_id": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
8
        "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
9
        "purpose": "SERVICES",
10
        "note": "Payment for consulting services",
11
        "status": "CAPTURED",
12
        "created_at": "2022-01-01T12:00:00Z",
13
        "updated_at": "2022-01-01T12:00:05Z"
14
    }
15
}

Payout Creation Failure Scenarios and Codes