> 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: customer_request.state.updated POST **When is this event triggered?** This event is created whenever a customer request's state is updated. This is typically caused by a customer approving or declining the request. Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/customer-request-api/customer-request-state-updated ## Request ### Payload - `type` (string, required) — The type of event that occurred. `customer_request.state.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` (WebhooksCustomerRequestStateUpdatedPayloadContentApplicationJsonSchemaData, required) — Data about the customer request that was updated. ## Types ### WebhooksCustomerRequestStateUpdatedPayloadContentApplicationJsonSchemaData Data about the customer request that was updated. - `id` (string, required) — A unique identifier provided by Cash App for the customer request. - `object` (WebhooksCustomerRequestStateUpdatedPayloadContentApplicationJsonSchemaDataObject, required) — A snapshot of the customer request data immediately after the customer request's state was updated. - `type` (string, required) — The resource type contained in the `object` field. For this event, it is `customer_request`. ### WebhooksCustomerRequestStateUpdatedPayloadContentApplicationJsonSchemaDataObject A snapshot of the customer request data immediately after the customer request's state was updated. - `request` (Request, required) — Describes a request from a client to perform a given action on a customer's account. ### Request Describes a request from a client to perform a given action on a customer's account. - `id` (string, required) — A unique identifier for the request issued by Cash App. Min length: `1` Max length: `128` - `status` (enum, required, default: PENDING) — Indicates if the state is approved, declined, or pending. Approved requests have grants, while pending and declined grants do not. Current values: - `PENDING`: The request has been created, but not responded to. - `PROCESSING`: The Cash App customer is actively responding to the request on their mobile device, and will require time to fill out information before the request is approved / declined. - `APPROVED`: The request was approved by the customer and grants have been created for the provided actions. - `DECLINED`: The request was denied by the customer. No grants were created. - Allowed values: `APPROVED`, `DECLINED`, `PENDING`, `PROCESSING` - `actions` (list of Action, required) — Represents what the client intends to do to a customer if given authorization. No duplicate action types allowed. Min number of items: `1` Max number of items: `5` - `redirect_url` (string, required) — If this request is responded to via mobile redirect, this field specifies the URL that Cash App will open for a customer in the mobile device's default browser after the request is approved or declined. - `created_at` (datetime, required) — When this customer request was created, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC). - `updated_at` (datetime, required) — When the customer request was last updated, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC). - `expires_at` (datetime, required) — When this customer request will be automatically declined by Cash App, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC). - `origin` (RequestOrigin, required) — Metadata describing how the customer request was created. - `channel` (enum, required) — How the customer is expected to interact with the request. - `IN_PERSON`: The customer presents or scans a QR code at a physical location to approve the request. - `ONLINE`: The customer scans a QR code or is redirected to Cash App from a browser context. - `IN_APP`: The customer scans a QR code or is redirected to Cash App from a native mobile application context. - Allowed values: `IN_PERSON`, `ONLINE`, `IN_APP` - `auth_flow_triggers` (RequestAuthFlowTriggers, optional) — While the request is `PENDING`, contains different methods that can be used to start the authorization flow in the Cash App mobile application. Its contents refresh each time the `refreshes_at` timestamp passes. When the data refreshes, you should update any buttons or QR codes referring to it immediately. After a request has been scanned (and is no longer in the `PENDING` status), this field will no longer be returned. - `grants` (list of Grant, optional) — If present, contains grants that can be used to perform actions specified in the request using the Network API. Each grant corresponds directly to an action on the request. Min number of items: `1` Max number of items: `5` - `reference_id` (string, optional) — A user-defined identifier for this request, typically used to associate the resource with a record in an external system. Min length: `1` Max length: `1024` - `requester_profile` (RequestRequesterProfile, optional) — Details about the brand or client that are requesting permission to perform the actions on the customer request. - `customer_profile` (RequestCustomerProfile, optional) — If the customer request was approved, contains the identity of the Cash App customer that approved it. - `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. - `customer_metadata` (CustomerMetadata, optional) — Metadata to associate with the customer that approves this request. ### Action Represents what the client intends to do to a customer if given authorization. - `type`: `ONE_TIME_PAYMENT` (One Time Payment Action) - `scope_id` (string, required) — ID of the client, brand, or merchant that will charge the customer. If a client ID is passed, the grant from this action can be used to create a payment for any merchant owned by the client. If a brand ID is passed, the grant from this action can be used to create a payment for any merchant that has a matching brand ID. If a merchant ID is passed, the grant from this action can be used to create a payment for the merchant with a matching ID. Min length: `1` Max length: `128` - `amount` (integer, optional) — Amount to charge the customer, in the lowest unit of the associated currency. Min value: `1` - `currency` (enum, optional) — 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` - `type`: `ON_FILE_PAYMENT` (On File Payment Action) - `scope_id` (string, required) — ID of the client or brand that will charge customers. If a client ID is passed, the grant from this action can be used to create a payment for any merchant owned by the client. If a brand ID is passed, the grant from this action can be used to create a payment for any merchant that has a matching brand ID. Merchant IDs may *not* be passed. Min length: `1` Max length: `128` - `account_reference_id` (string, optional) — Identifier of the account or customer associated to the on file action. - `type`: `ON_FILE_DEPOSIT` (On File Deposit Action) - `account_reference_id` (string, required) — Identifier of the account or customer associated to the on file action. - `scope_id` (string, required) — ID of the client or brand that indicates the set of merchants that will deposit to customers. If a client ID is passed, the grant from this action can be used to create a deposit for any merchant owned by the client. If a brand ID is passed, the grant from this action can be used to create a deposit for any merchant that has a matching brand ID. Min length: `1` Max length: `128` - `type`: `ON_FILE_PAYOUT` (On File Payout Action) - `scope_id` (string, required) — ID of the client or brand that indicates the set of merchants that will payout to customers. If a client ID is passed, the grant from this action can be used to create a payout for any merchant owned by the client. If a brand ID is passed, the grant from this action can be used to create a payout for any merchant that has a matching brand ID. Merchant IDs may *not* be passed. Min length: `1` Max length: `128` - `account_reference_id` (string, optional) — Identifier of the account or customer associated to the on file action. - `type`: `LINK_ACCOUNT` (Link Account Action) - `type`: `CHECKING_BALANCE` (Checking Balance Action) - `scope_id` (string, required) — ID of the client or brand requesting access to read the customer's balances. If a client ID is passed, the grant from this action can be used to read balances on behalf of the client. If a brand ID is passed, the grant from this action can be used to read balances on behalf of any merchant that has a matching brand ID. Merchant IDs may *not* be passed. Min length: `1` Max length: `128` ### RequestOrigin Metadata describing how the customer request was created. - `type` (enum, required) — The method used to create the customer request. - `DIRECT` - the client or SDKs created this customer request by calling the "CreateCustomerRequest" endpoint - `REQUEST_INITIATOR` - a customer interacted with a request initiator and caused Cash App to create a customer request. - Allowed values: `DIRECT`, `REQUEST_INITIATOR` - `id` (string, optional) — If present, is the ID of the initiator used to create this request. Min length: `1` Max length: `128` ### RequestAuthFlowTriggers While the request is `PENDING`, contains different methods that can be used to start the authorization flow in the Cash App mobile application. Its contents refresh each time the `refreshes_at` timestamp passes. When the data refreshes, you should update any buttons or QR codes referring to it immediately. After a request has been scanned (and is no longer in the `PENDING` status), this field will no longer be returned. - `qr_code_image_url` (string, required) — Link to a QR code customers can scan with Cash App to authorize the given action, encoded as a PNG file. Min length: `8` Max length: `1024` - `qr_code_svg_url` (string, required) — Link to a QR code customers can scan with Cash App to authorize the given action, encoded as an SVG file. Min length: `8` Max length: `1024` - `mobile_url` (string, required) — If on an Android or iOS device, the URL to redirect customers to in order to authorize the given action. Min length: `8` Max length: `1024` - `refreshes_at` (datetime, required) — When the QR code image URL will be rotated. Generally, it will rotate every ~20 seconds and become invalid after 30 seconds. - `desktop_url` (string, optional) — If on a desktop browser, the URL to redirect customers to in order to authorize the given action. Min length: `8` Max length: `1024` ### Grant Describes a grant that can be used to perform actions specified in a customer request using the Network API. - `id` (string, required) — Unique identifier for this grant issued by Cash App. Min length: `1` Max length: `256` - `customer_id` (string, required) — ID of the customer that approved this grant. Min length: `1` Max length: `128` - `request_id` (string, required) — A unique identifier issued by Cash App for the customer request that resulted in the creation of this grant. Min length: `1` Max length: `128` - `action` (Action, required) — Represents what the client intends to do to a customer if given authorization. - `status` (enum, required) — Describes whether or not this grant can be used to perform the action associated with it. If `ACTIVE`, it can be used to perform the action. If `EXPIRED`, it may no longer be used to perform the action due to the current time being past the "expires_at" time. If `CONSUMED`, it was already redeemed to perform the action and cannot be used again. If `REVOKED`, the customer or merchant explicitly unauthorized the grant, preventing it from being used to perform the action. - Allowed values: `ACTIVE`, `CONSUMED`, `REVOKED`, `EXPIRED` - `type` (enum, required) — Describes whether this grant can be only be used once (`ONE_TIME`) or repeatedly (`EXTENDED`). - Allowed values: `ONE_TIME`, `EXTENDED` - `channel` (enum, required) — How the customer is expected to interact with the request. - `IN_PERSON`: The customer presents or scans a QR code at a physical location to approve the request. - `ONLINE`: The customer scans a QR code or is redirected to Cash App from a browser context. - `IN_APP`: The customer scans a QR code or is redirected to Cash App from a native mobile application context. - Allowed values: `IN_PERSON`, `ONLINE`, `IN_APP` - `created_at` (datetime, required) — When this grant was created, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC). - `updated_at` (datetime, required) — When this grant was last updated, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC). - `expires_at` (datetime, optional) — If present, indicates when the grant's status will become `EXPIRED`, preventing a client from using it to create payments or refunds. The timestamp is in the [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC). ### RequestRequesterProfile Details about the brand or client that are requesting permission to perform the actions on the customer request. - `name` (string, required) — Name of the brand to be shown in Cash App next to payments. Min length: `1` Max length: `1024` - `logo_url` (string, required) — URL to the image of the entity (brand or client) that is requesting permission to perform the actions on the customer request. Formats: - `.jpg` - `.jpeg` - `.png` Min length: `8` Max length: `8000` ### RequestCustomerProfile If the customer request was approved, contains the identity of the Cash App customer that approved it. - `id` (string, required) — Unique identifier for this customer issued by Cash App. Min length: `1` Max length: `128` - `cashtag` (string, required) — Public identifier for the customer on Cash App. [Learn more](https://cash.app/help/us/en-us/3123-cashtags). Min length: `1` Max length: `1024` ### CustomerMetadata Metadata to associate with the customer that approves this request. - `reference_id` (string, optional) — The `reference_id` of the customer approving this request. When a customer approves this request, that customer will be associated with this `reference_id`.