> 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: refund.status.updated

POST 

**When is this event triggered?**

This event is created whenever a refund status is changed. The status change can be due to a couple different things:
  - An API client-initiated action to void or capture the refund
  - A refund auto-voiding after 7 days of not being captured

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

## Request

### Payload

- `type` (string, required) — The type of event that occurred. `refund.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` (RefundStatusUpdatedPayloadData, required) — Data about the refund that had a status change.

## Types

### RefundStatusUpdatedPayloadData

Data about the refund that had a status change.

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

### RefundStatusUpdatedPayloadDataObject

A snapshot of the refund immediately after the refund's status changed.

- `refund` (Refund, required)

### Refund

- `id` (string, required) — Unique identifier for this refund issued by Cash App. Min length: `1` Max length: `128`
- `amount` (integer, required) — Amount of money to refund, in the lowest denomination of currency on the refund. 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`
- `customer_id` (string, required) — ID of the customer that received this refund. Min length: `1` Max length: `128`
- `merchant_id` (string, required) — ID of the merchant that issued this refund. Min length: `1` Max length: `128`
- `status` (enum, required) — The step of the refund processing lifecycle that this refund is currently at. - `AUTHORIZED` - `CAPTURED` - `VOIDED` - `DECLINED`
  - Allowed values: `AUTHORIZED`, `CAPTURED`, `VOIDED`, `DECLINED`
- `created_at` (datetime, required) — When this refund was created, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
- `updated_at` (datetime, required) — When this refund was last updated, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
- `grant_id` (string, optional) — This is currently unused and empty. Min length: `1` Max length: `256`
- `payment_id` (string, optional) — This is currently unused and empty. Min length: `1` Max length: `128`
- `reference_id` (string, optional) — A user-defined identifier for this refund, typically used to associate the refund with a record in an external system. 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 refund was declined, contains a list of the reasons why it was declined. Min number of items: `1`

### 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`