> This page is for Cash App Pay Partner API.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.cash.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.cash.app/_mcp/server.

### Schema (`response.body`)

```yaml
openapi: 3.1.0
info:
  title: API
  version: 1.0.0
paths:
  /payouts:
    post:
      operationId: subpackagePayouts_create-payout
      summary: Create payout
      description: >-
        <Warning title="Early Access" icon="robot-astromech">

        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)

        </Warning>


        Creates a payout to a customer. A payout allows a merchant to send money
        to a customer's Cash App account.


        **This endpoint is not rate-limited.**


        Scopes: `PAYOUTS_WRITE`
      tags:
        - subpackage_payouts
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payouts_CreatePayoutResponse'
        '400':
          description: >-
            Bad Request


            If a `PAYOUT_DECLINE_*` error is returned, the payout will still be
            created, but with a `DECLINED` status. This payout will then appear
            in the response payload.


            <Note>

            **`PAYOUT_DECLINE_*` errors consume one-time use grants.**
             This means you must repeat the Customer Request flow to get a new grant if you want to try taking the payout again. All other errors will not consume grants.
             </Note>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePayoutRequestBadRequestErrorBody'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                idempotency_key:
                  $ref: '#/components/schemas/IdempotencyKey'
                payout:
                  $ref: '#/components/schemas/payouts_CreatePayoutRequestPayout'
                  description: Data about the payout to create.
              required:
                - idempotency_key
                - payout
tags:
  - name: subpackage_payouts
servers:
  - url: https://api.cash.app/network/v1
    description: Production
  - url: https://sandbox.api.cash.app/network/v1
    description: Sandbox
components:
  schemas:
    IdempotencyKey:
      type: string
      minLength: 1
      maxLength: 64
      description: >-
        A unique identifier which can be used by Cash App to de-duplicate
        retries of this request, making it idempotent. For more information, see
        [Idempotency](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/idempotency).
      title: IdempotencyKey
    Currency:
      type: string
      enum:
        - USD
      description: >-
        Indicates the country associated with an entity. Values are from the
        [ISO-4217 Alpha-3](https://www.iso.org/iso-4217-currency-codes.html)
        specification.


        Current values:


        - `USD`: United States Dollar
      title: Currency
    payouts_PayoutPurpose:
      type: string
      enum:
        - SERVICES
        - EARNED_WAGE_ACCESS
      description: The purpose or intent of the payout.
      title: PayoutPurpose
    Metadata:
      type: object
      additionalProperties:
        type: string
      description: >-
        Freeform key-value pairs of arbitrary data associated with this
        resource.


        Keys and values must be passed as strings and not contain any personally
        identifiable information (PII).


        Min keys: `0`

        Max keys: `50`



        > Note: Nested keys are not supported.
      title: Metadata
    payouts_CreatePayoutRequestPayout:
      type: object
      properties:
        amount:
          type: integer
          minimum: 1
          description: >-
            The amount of money to pay the customer, in the lowest denomination
            of currency for the payout.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        merchant_id:
          type: string
          minLength: 1
          maxLength: 128
          description: |-
            ID of the merchant making the payout.

            Min length: `1`
            Max length: `128`
        grant_id:
          type: string
          minLength: 1
          maxLength: 256
          description: >-
            A grant ID from the Customer Request API that indicates permission
            to make the payout.


            Min length: `1`

            Max length: `256`
        purpose:
          $ref: '#/components/schemas/payouts_PayoutPurpose'
        reference_id:
          type: string
          minLength: 1
          maxLength: 1024
          description: >-
            A user-defined identifier for this payout, typically used to
            associate the payout with a record in an external system.


            Min length: `1`

            Max length: `1024`
        capture:
          type: boolean
          default: true
          description: >-
            Whether or not to automatically capture the payout once it's
            created.


            Default: `true`
        note:
          type: string
          minLength: 1
          maxLength: 1024
          description: |-
            A note about the payout that will be shown to the customer.

            Min length: `1`
            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - amount
        - currency
        - merchant_id
        - grant_id
        - purpose
        - capture
        - note
      description: Data about the payout to create.
      title: CreatePayoutRequestPayout
    payouts_PayoutStatus:
      type: string
      enum:
        - CAPTURED
        - DECLINED
        - AUTHORIZED
        - INITIATED
        - VOIDED
      description: >-
        The step of the payout processing lifecycle that this payout is
        currently at.


        - `CAPTURED` - Payout is captured and funds have been sent

        - `DECLINED` - Payout was declined

        - `AUTHORIZED` - Payout is authorized but not yet captured

        - `INITIATED` - Payout has been created but no money movement has
        happened yet

        - `VOIDED` - Payout authorization was released and funds were not sent
      title: PayoutStatus
    feePlans_FeeRate:
      type: object
      properties:
        basis_points:
          type: integer
          description: >-
            The variable fee charged for processing the payment expressed as
            1/100th of a percentage.
        fixed_amount:
          type: integer
          description: >-
            The amount charged for processing the payment, in the lowest
            denomination of currency on the payment.
             **Note: The currency for the fee is found on the fee plan.**
      description: >-
        A fee rate contains the components of a fee charged by Cash App to
        partners for a given payment.
      title: FeeRate
    ErrorCategory:
      type: string
      enum:
        - API_ERROR
        - AUTHENTICATION_ERROR
        - BRAND_ERROR
        - DISPUTE_ERROR
        - MERCHANT_ERROR
        - INVALID_REQUEST_ERROR
        - PAYMENT_PROCESSING_ERROR
        - RATE_LIMIT_ERROR
        - WEBHOOK_ERROR
        - API_KEY_ERROR
        - GRANT_ERROR
      description: The high-level reason the error occurred.
      title: ErrorCategory
    Error:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
          description: The high-level reason the error occurred.
        code:
          type: string
          description: >-
            A unique identifier for the specific type of error that occurred.
            For more information, see [Error Code
            Reference](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/errors/error-code-reference).


            Min length: `1`
        detail:
          type: string
          description: >-
            Human-readable description of why the error occurred and how to
            resolve it.


            Min length: `1`
        field:
          type: string
          description: >-
            The field in the request that caused the error, using array and
            object dot notation.


            Min length: `1`
      required:
        - category
        - code
      description: Represents an error encountered during a request to the API.
      title: Error
    payouts_Payout:
      type: object
      properties:
        payout_id:
          type: string
          minLength: 1
          maxLength: 128
          description: |-
            Unique identifier for this payout issued by Cash App.

            Min length: `1`
            Max length: `128`
        grant_id:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            ID of the grant used to create this payout.

            Min length: `1`
            Max length: `256`
        amount:
          type: integer
          minimum: 1
          description: >-
            The amount of money to pay, in the lowest denomination of currency
            on the payout. This is the _original_ amount authorized when the
            payout was created.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        status:
          $ref: '#/components/schemas/payouts_PayoutStatus'
        merchant_id:
          type: string
          minLength: 1
          maxLength: 128
          description: |-
            ID of the merchant that made this payout.

            Min length: `1`
            Max length: `128`
        customer_id:
          type: string
          minLength: 1
          maxLength: 128
          description: |-
            ID of the customer that received this payout.

            Min length: `1`
            Max length: `128`
        purpose:
          $ref: '#/components/schemas/payouts_PayoutPurpose'
        authorized_amount:
          type: integer
          minimum: 0
          description: >-
            The amount of money on this payout that has been authorized. The
            amount will be in the lowest denomination of the currency on the
            payout.


            Min value: `0`
        captured_amount:
          type: integer
          minimum: 0
          description: >-
            The amount of money on this payout that has been allocated for
            settlement. The amount will be in the lowest denomination of the
            currency on the payout.


            Min value: `0`
        declined_amount:
          type: integer
          minimum: 0
          description: >-
            The amount of money on this payout that was declined. The amount
            will be in the lowest denomination of the currency on the payout.


            Min value: `0`
        voided_amount:
          type: integer
          minimum: 0
          description: >-
            The amount of money on this payout that is no longer authorized and
            has been released. The amount will be in the lowest denomination of
            the currency on the payout.


            Min value: `0`
        reference_id:
          type: string
          minLength: 1
          maxLength: 1024
          description: >-
            A user-defined identifier for this payout, typically used to
            associate the payout with a record in an external system.


            Min length: `1`

            Max length: `1024`
        fee_amount:
          type: number
          format: double
          minimum: 0
          description: >-
            The total fee amount that was charged to the merchant for processing
            this payout.
        fee_rate:
          $ref: '#/components/schemas/feePlans_FeeRate'
          description: >-
            The breakdown of the fee that was charged to the merchant for
            processing this payout.
        note:
          type: string
          minLength: 1
          maxLength: 1024
          description: |-
            A note about the payout that will be shown to the customer.

            Min length: `1`
            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the payout was declined, contains a list of the reasons why it
            was declined.


            Min number of items: `1`
      required:
        - payout_id
        - grant_id
        - amount
        - currency
        - status
        - merchant_id
        - purpose
      title: Payout
    payouts_CreatePayoutResponse:
      type: object
      properties:
        payout:
          $ref: '#/components/schemas/payouts_Payout'
      title: CreatePayoutResponse
    CreatePayoutRequestBadRequestErrorBody:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: |-
            A list of errors indicating why the request failed.

            Min number of items: `1`
        payout:
          $ref: '#/components/schemas/payouts_Payout'
      required:
        - errors
      title: CreatePayoutRequestBadRequestErrorBody

```

**`Example`**

```json Example
{
  "payout_id": "CAPO_4nn21zy6t0v2yhqg5bvhk7xkq",
  "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50",
  "amount": 1500,
  "currency": "USD",
  "status": "CAPTURED",
  "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
  "purpose": "SERVICES",
  "authorized_amount": 1500,
  "captured_amount": 1500,
  "declined_amount": 0,
  "voided_amount": 0,
  "reference_id": "external-id",
  "fee_amount": 50,
  "fee_rate": {
    "basis_points": 160,
    "fixed_amount": 20
  },
  "note": "Payment for consulting work completed in January",
  "metadata": {},
  "decline_errors": [
    {
      "category": "INVALID_REQUEST_ERROR",
      "code": "MISSING_REQUIRED_FIELD",
      "detail": "Missing required parameter.",
      "field": "field_a[2].field_b"
    }
  ]
}
```