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

# Event: payout.status.updated

POST 

**When is this event triggered?**

This event is created whenever a payout status is changed. The status change can be due to a couple different things:
  - A payout is created
  - An API client-initiated action to capture or void the payout

For an auto-captured payout, Cash App sends a single status update after capture.

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/payout-status-updated

## Request

### Payload

- `type` (string, required) — The type of event that occurred. `payout.status.updated` for this event.
- `event_id` (string, required) — A unique identifier provided by Cash App for the event.
- `created_at` (datetime, required) — When this event occured in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC). The time that the event is delivered may be significantly later than this timestamp due to webhooks being retried for up to 72 hours.
- `data` (PayoutStatusUpdatedPayloadData, required) — Data about the payout that had a status change.

## Types

### PayoutStatusUpdatedPayloadData

Data about the payout that had a status change.

- `id` (string, required) — A unique identifier provided by Cash App for the payout.
- `object` (PayoutStatusUpdatedPayloadDataObject, required) — A snapshot of the payout data immediately after the payout's status changed.
- `type` (string, required) — The resource type contained in the `object` field. For this event, it is `payout`.

### PayoutStatusUpdatedPayloadDataObject

A snapshot of the payout data immediately after the payout's status changed.

- `payout` (Payout, required)

### Payout

- `payout_id` (string, required) — Unique identifier for this payout issued by Cash App. Min length: `1` Max length: `128`
- `grant_id` (string, required) — ID of the grant used to create this payout. Min length: `1` Max length: `256`
- `amount` (integer, required) — 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` (enum, required) — 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
  - Allowed values: `USD`
- `status` (enum, required) — 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
  - Allowed values: `CAPTURED`, `DECLINED`, `AUTHORIZED`, `INITIATED`, `VOIDED`
- `merchant_id` (string, required) — ID of the merchant that made this payout. Min length: `1` Max length: `128`
- `purpose` (enum, required) — The purpose or intent of the payout.
  - Allowed values: `SERVICES`, `EARNED_WAGE_ACCESS`
- `customer_id` (string, optional) — ID of the customer that received this payout. Min length: `1` Max length: `128`
- `authorized_amount` (integer, optional) — 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` (integer, optional) — 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` (integer, optional) — 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` (integer, optional) — 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` (string, optional) — 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` (double, optional) — The total fee amount that was charged to the merchant for processing this payout.
- `fee_rate` (FeeRate, optional) — The breakdown of the fee that was charged to the merchant for processing this payout.
- `note` (string, optional) — A note about the payout that will be shown to the customer. Min length: `1` Max length: `1024`
- `metadata` (map from string to string, optional) — 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.
- `decline_errors` (list of Error, optional) — If the payout was declined, contains a list of the reasons why it was declined. Min number of items: `1`

### FeeRate

A fee rate contains the components of a fee charged by Cash App to partners for a given payment.

- `basis_points` (integer, optional) — The variable fee charged for processing the payment expressed as 1/100th of a percentage.
- `fixed_amount` (integer, optional) — 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.**

### Error

Represents an error encountered during a request to the API.

- `category` (enum, required) — The high-level reason the error occurred.
  - Allowed values: `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`
- `code` (string, required) — 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` (string, optional) — Human-readable description of why the error occurred and how to resolve it. Min length: `1`
- `field` (string, optional) — The field in the request that caused the error, using array and object dot notation. Min length: `1`