Requests_retrieve-request_Response_200

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/cash-app/main/json-schema/cash-app-requests-retrieve-request-response-200-schema.json",
  "title": "Requests_retrieve-request_Response_200",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/cash-app-requests-api-openapi.yml#/components/schemas/Requests_retrieve-request_Response_200",
  "type": "object",
  "properties": {
    "request": {
      "$ref": "#/$defs/Request"
    }
  },
  "required": [
    "request"
  ],
  "$defs": {
    "Action": {
      "oneOf": [
        {
          "$ref": "#/$defs/OneTimePaymentAction"
        },
        {
          "$ref": "#/$defs/OnFilePaymentAction"
        },
        {
          "$ref": "#/$defs/OnFileDepositAction"
        },
        {
          "$ref": "#/$defs/OnFilePayoutAction"
        },
        {
          "$ref": "#/$defs/LinkAccountAction"
        },
        {
          "$ref": "#/$defs/CheckingBalanceAction"
        }
      ],
      "description": "Represents what the client intends to do to a customer if given authorization.",
      "title": "Action"
    },
    "Channel": {
      "type": "string",
      "enum": [
        "IN_PERSON",
        "ONLINE",
        "IN_APP"
      ],
      "description": "How the customer is expected to interact with the request.\n\n- `IN_PERSON`: The customer presents or scans a QR code at a physical location to approve the request.\n- `ONLINE`: The customer scans a QR code or is redirected to Cash App from a browser context.\n- `IN_APP`: The customer scans a QR code or is redirected to Cash App from a native mobile application context.",
      "title": "Channel"
    },
    "CheckingBalanceAction": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/$defs/CheckingBalanceActionType",
          "description": "The type of the action (`CHECKING_BALANCE`)."
        },
        "scope_id": {
          "type": "string",
          "description": "ID of the client or brand requesting access to read the customer's balances.\n\nIf a client ID is passed, the grant from this action can be used to read balances on behalf of the client.\n\nIf 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.\n\nMerchant IDs may *not* be passed.\n\nMin length: `1`\nMax length: `128`"
        }
      },
      "required": [
        "type",
        "scope_id"
      ],
      "description": "Describes an intent for a client to read a customer's Cash App checking balance until the customer revokes the grant.\n\n**Beta:** This action is in beta.",
      "title": "CheckingBalanceAction"
    },
    "CheckingBalanceActionType": {
      "type": "string",
      "enum": [
        "CHECKING_BALANCE"
      ],
      "description": "The type of the action (`CHECKING_BALANCE`).",
      "title": "CheckingBalanceActionType"
    },
    "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.\n\nCurrent values:\n\n- `USD`: United States Dollar",
      "title": "Currency"
    },
    "CustomerMetadata": {
      "type": "object",
      "properties": {
        "reference_id": {
          "type": "string",
          "description": "The `reference_id` of the customer approving this request. When a customer approves this request, that customer will be associated with this `reference_id`."
        }
      },
      "description": "Metadata to associate with the customer that approves this request.",
      "title": "CustomerMetadata"
    },
    "Grant": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for this grant issued by Cash App.\n\nMin length: `1`\nMax length: `256`"
        },
        "customer_id": {
          "type": "string",
          "description": "ID of the customer that approved this grant.\n\nMin length: `1`\nMax length: `128`"
        },
        "request_id": {
          "type": "string",
          "description": "A unique identifier issued by Cash App for the customer request that resulted in the creation of this grant.\n\nMin length: `1`\nMax length: `128`"
        },
        "action": {
          "$ref": "#/$defs/Action"
        },
        "status": {
          "$ref": "#/$defs/GrantStatus",
          "description": "Describes whether or not this grant can be used to perform the action associated with it.\n\nIf `ACTIVE`, it can be used to perform the action.\n\nIf `EXPIRED`, it may no longer be used to perform the action due to the current time being past the \"expires_at\" time.\n\nIf `CONSUMED`, it was already redeemed to perform the action and cannot be used again.\n\nIf `REVOKED`, the customer or merchant explicitly unauthorized the grant, preventing it from being used to perform the action."
        },
        "type": {
          "$ref": "#/$defs/GrantType",
          "description": "Describes whether this grant can be only be used once (`ONE_TIME`) or repeatedly (`EXTENDED`)."
        },
        "channel": {
          "$ref": "#/$defs/Channel"
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "description": "When this grant was created, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC)."
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "description": "When this grant was last updated, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC)."
        },
        "expires_at": {
          "type": "string",
          "format": "date-time",
          "description": "If present, indicates when the grant's status will become `EXPIRED`, preventing a client from using it to create payments or refunds.\n\nThe timestamp is in the [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC)."
        }
      },
      "required": [
        "id",
        "customer_id",
        "request_id",
        "action",
        "status",
        "type",
        "channel",
        "created_at",
        "updated_at"
      ],
      "description": "Describes a grant that can be used to perform actions specified in a customer request using the Network API.",
      "title": "Grant"
    },
    "GrantStatus": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "CONSUMED",
        "REVOKED",
        "EXPIRED"
      ],
      "description": "Describes whether or not this grant can be used to perform the action associated with it.\n\nIf `ACTIVE`, it can be used to perform the action.\n\nIf `EXPIRED`, it may no longer be used to perform the action due to the current time being past the \"expires_at\" time.\n\nIf `CONSUMED`, it was already redeemed to perform the action and cannot be used again.\n\nIf `REVOKED`, the customer or merchant explicitly unauthorized the grant, preventing it from being used to perform the action.",
      "title": "GrantStatus"
    },
    "GrantType": {
      "type": "string",
      "enum": [
        "ONE_TIME",
        "EXTENDED"
      ],
      "description": "Describes whether this grant can be only be used once (`ONE_TIME`) or repeatedly (`EXTENDED`).",
      "title": "GrantType"
    },
    "LinkAccountAction": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/$defs/LinkAccountActionType",
          "description": "The type of the action (`LINK_ACCOUNT`)."
        }
      },
      "required": [
        "type"
      ],
      "description": "Describes an intent for a client to manage a customer's merchant profiles in Cash App.",
      "title": "LinkAccountAction"
    },
    "LinkAccountActionType": {
      "type": "string",
      "enum": [
        "LINK_ACCOUNT"
      ],
      "description": "The type of the action (`LINK_ACCOUNT`).",
      "title": "LinkAccountActionType"
    },
    "Metadata": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Freeform key-value pairs of arbitrary data associated with this resource.\n\nKeys and values must be passed as strings and not contain any personally identifiable information (PII).\n\nMin keys: `0`\nMax keys: `50`\n\n> Note: Nested keys are not supported.",
      "title": "Metadata"
    },
    "OnFileDepositAction": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/$defs/OnFileDepositActionType",
          "description": "The type of the action (`ON_FILE_DEPOSIT`)."
        },
        "scope_id": {
          "type": "string",
          "description": "ID of the client or brand that indicates the set of merchants that will deposit to customers.\n\nIf a client ID is passed, the grant from this action can be used to create a deposit for any merchant owned by the client.\n\nIf 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.\nMin length: `1`\nMax length: `128`"
        },
        "account_reference_id": {
          "type": "string",
          "description": "Identifier of the account or customer associated to the on file action."
        }
      },
      "required": [
        "type",
        "scope_id",
        "account_reference_id"
      ],
      "description": "Describes an intent for a client to deposit funds into the Cash App account balances in perpetuity until the Cash App account revokes the grant.",
      "title": "OnFileDepositAction"
    },
    "OnFileDepositActionType": {
      "type": "string",
      "enum": [
        "ON_FILE_DEPOSIT"
      ],
      "description": "The type of the action (`ON_FILE_DEPOSIT`).",
      "title": "OnFileDepositActionType"
    },
    "OnFilePaymentAction": {
      "type": "object",
      "properties": {
        "scope_id": {
          "type": "string",
          "description": "ID of the client or brand that will charge customers.\n\nIf a client ID is passed, the grant from this action can be used to create a payment for any merchant owned by the client.\n\nIf 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.\n\nMerchant IDs may *not* be passed.\n\nMin length: `1`\nMax length: `128`"
        },
        "type": {
          "$ref": "#/$defs/OnFilePaymentActionType",
          "description": "The type of the action (`ON_FILE_PAYMENT`)."
        },
        "account_reference_id": {
          "type": "string",
          "description": "Identifier of the account or customer associated to the on file action."
        }
      },
      "required": [
        "scope_id",
        "type"
      ],
      "description": "Describes an intent for a client to store a customer's account, allowing a client to create payments or issue refunds for it on a recurring basis.",
      "title": "OnFilePaymentAction"
    },
    "OnFilePaymentActionType": {
      "type": "string",
      "enum": [
        "ON_FILE_PAYMENT"
      ],
      "default": "ON_FILE_PAYMENT",
      "description": "The type of the action (`ON_FILE_PAYMENT`).",
      "title": "OnFilePaymentActionType"
    },
    "OnFilePayoutAction": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/$defs/OnFilePayoutActionType",
          "description": "The type of the action (`ON_FILE_PAYOUT`)."
        },
        "scope_id": {
          "type": "string",
          "description": "ID of the client or brand that indicates the set of merchants that will payout to customers.\n\nIf a client ID is passed, the grant from this action can be used to create a payout for any merchant owned by the client.\n\nIf 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.\n\nMerchant IDs may *not* be passed.\n\nMin length: `1`\nMax length: `128`"
        },
        "account_reference_id": {
          "type": "string",
          "description": "Identifier of the account or customer associated to the on file action."
        }
      },
      "required": [
        "type",
        "scope_id"
      ],
      "description": "Describes an intent for a client to payout funds from the Cash App account balances in perpetuity until the Cash App account revokes the grant.",
      "title": "OnFilePayoutAction"
    },
    "OnFilePayoutActionType": {
      "type": "string",
      "enum": [
        "ON_FILE_PAYOUT"
      ],
      "description": "The type of the action (`ON_FILE_PAYOUT`).",
      "title": "OnFilePayoutActionType"
    },
    "OneTimePaymentAction": {
      "type": "object",
      "properties": {
        "amount": {
          "type": "integer",
          "description": "Amount to charge the customer, in the lowest unit of the associated currency.\n\nMin value: `1`"
        },
        "currency": {
          "$ref": "#/$defs/Currency"
        },
        "scope_id": {
          "type": "string",
          "description": "ID of the client, brand, or merchant that will charge the customer.\n\nIf a client ID is passed, the grant from this action can be used to create a payment for any merchant owned by the client.\n\nIf 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.\n\nIf a merchant ID is passed, the grant from this action can be used to create a payment for the merchant with a matching ID.\n\nMin length: `1`\nMax length: `128`"
        },
        "type": {
          "$ref": "#/$defs/OneTimePaymentActionType",
          "description": "The type of the action (`ONE_TIME_PAYMENT`)."
        }
      },
      "required": [
        "scope_id",
        "type"
      ],
      "description": "Describes an intent for a client to charge a customer a given amount.\n\nNote the following restrictions when using this action:\n\n- If no amount is provided to the action, the payment charged may be **any** amount.\n- If `amount` is provided, `currency` must be provided too (and vice versa).",
      "title": "OneTimePaymentAction"
    },
    "OneTimePaymentActionType": {
      "type": "string",
      "enum": [
        "ONE_TIME_PAYMENT"
      ],
      "description": "The type of the action (`ONE_TIME_PAYMENT`).",
      "title": "OneTimePaymentActionType"
    },
    "Request": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "A unique identifier for the request issued by Cash App.\n\nMin length: `1`\nMax length: `128`"
        },
        "status": {
          "$ref": "#/$defs/RequestStatus",
          "description": "Indicates if the state is approved, declined, or pending. Approved requests have grants, while pending and declined grants do not.\n\nCurrent values:\n\n- `PENDING`: The request has been created, but not responded to.\n- `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.\n- `APPROVED`: The request was approved by the customer and grants have been created for the provided actions.\n- `DECLINED`: The request was denied by the customer. No grants were created."
        },
        "actions": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Action"
          },
          "description": "Represents what the client intends to do to a customer if given authorization.\n\nNo duplicate action types allowed.\n\nMin number of items: `1`\nMax number of items: `5`"
        },
        "auth_flow_triggers": {
          "$ref": "#/$defs/RequestAuthFlowTriggers",
          "description": "While the request is `PENDING`, contains different methods that can be used to start\nthe authorization flow in the Cash App mobile application. Its contents refresh each time\nthe `refreshes_at` timestamp passes. When the\ndata refreshes, you should update any buttons\nor QR codes referring to it immediately.\n\nAfter a request has been scanned (and is no\nlonger in the `PENDING` status), this\nfield will no longer be returned."
        },
        "redirect_url": {
          "type": "string",
          "format": "uri",
          "description": "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": {
          "type": "string",
          "format": "date-time",
          "description": "When this customer request was created, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC)."
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "description": "When the customer request was last updated, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC)."
        },
        "expires_at": {
          "type": "string",
          "format": "date-time",
          "description": "When this customer request will be automatically declined by Cash App, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC)."
        },
        "origin": {
          "$ref": "#/$defs/RequestOrigin",
          "description": "Metadata describing how the customer request was created."
        },
        "channel": {
          "$ref": "#/$defs/Channel"
        },
        "grants": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Grant"
          },
          "description": "If present, contains grants that can be used to perform actions specified in the request using the Network API.\n\nEach grant corresponds directly to an action on the request.\n\nMin number of items: `1`\nMax number of items: `5`"
        },
        "reference_id": {
          "type": "string",
          "description": "A user-defined identifier for this request, typically used to associate the resource with a record in an external system.\n\nMin length: `1`\nMax length: `1024`"
        },
        "requester_profile": {
          "$ref": "#/$defs/RequestRequesterProfile",
          "description": "Details about the brand or client that are requesting permission to perform the actions on the customer request."
        },
        "customer_profile": {
          "$ref": "#/$defs/RequestCustomerProfile",
          "description": "If the customer request was approved, contains the identity of the Cash App customer that approved it."
        },
        "metadata": {
          "$ref": "#/$defs/Metadata"
        },
        "customer_metadata": {
          "$ref": "#/$defs/CustomerMetadata"
        }
      },
      "required": [
        "id",
        "status",
        "actions",
        "redirect_url",
        "created_at",
        "updated_at",
        "expires_at",
        "origin",
        "channel"
      ],
      "description": "Describes a request from a client to perform a given action on a customer's account.",
      "title": "Request"
    },
    "RequestAuthFlowTriggers": {
      "type": "object",
      "properties": {
        "qr_code_image_url": {
          "type": "string",
          "format": "uri",
          "description": "Link to a QR code customers can scan with Cash App to authorize the given action, encoded as a PNG file.\n\nMin length: `8`\nMax length: `1024`"
        },
        "qr_code_svg_url": {
          "type": "string",
          "format": "uri",
          "description": "Link to a QR code customers can scan with Cash App to authorize the given action, encoded as an SVG file.\n\nMin length: `8`\nMax length: `1024`"
        },
        "mobile_url": {
          "type": "string",
          "format": "uri",
          "description": "If on an Android or iOS device, the URL to redirect customers to in order to authorize the given action.\n\nMin length: `8`\nMax length: `1024`"
        },
        "refreshes_at": {
          "type": "string",
          "format": "date-time",
          "description": "When the QR code image URL will be rotated. Generally, it will rotate every ~20 seconds and become invalid after 30 seconds."
        },
        "desktop_url": {
          "type": "string",
          "format": "uri",
          "description": "If on a desktop browser, the URL to redirect customers to in order to authorize the given action.\n\nMin length: `8`\nMax length: `1024`"
        }
      },
      "required": [
        "qr_code_image_url",
        "qr_code_svg_url",
        "mobile_url",
        "refreshes_at"
      ],
      "description": "While the request is `PENDING`, contains different methods that can be used to start\nthe authorization flow in the Cash App mobile application. Its contents refresh each time\nthe `refreshes_at` timestamp passes. When the\ndata refreshes, you should update any buttons\nor QR codes referring to it immediately.\n\nAfter a request has been scanned (and is no\nlonger in the `PENDING` status), this\nfield will no longer be returned.",
      "title": "RequestAuthFlowTriggers"
    },
    "RequestCustomerProfile": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for this customer issued by Cash App.\n\nMin length: `1`\nMax length: `128`"
        },
        "cashtag": {
          "type": "string",
          "description": "Public identifier for the customer on Cash App. [Learn more](https://cash.app/help/us/en-us/3123-cashtags).\n\nMin length: `1`\nMax length: `1024`"
        }
      },
      "required": [
        "id",
        "cashtag"
      ],
      "description": "If the customer request was approved, contains the identity of the Cash App customer that approved it.",
      "title": "RequestCustomerProfile"
    },
    "RequestOrigin": {
      "type": "object",
      "properties": {
        "type": {
          "$ref": "#/$defs/RequestOriginType",
          "description": "The method used to create the customer request.\n\n- `DIRECT` - the client or SDKs created this customer request by calling the \"CreateCustomerRequest\" endpoint\n- `REQUEST_INITIATOR` - a customer interacted with a request initiator and caused Cash App to create a customer request."
        },
        "id": {
          "type": "string",
          "description": "If present, is the ID of the initiator used to create this request.\n\nMin length: `1`\nMax length: `128`"
        }
      },
      "required": [
        "type"
      ],
      "description": "Metadata describing how the customer request was created.",
      "title": "RequestOrigin"
    },
    "RequestOriginType": {
      "type": "string",
      "enum": [
        "DIRECT",
        "REQUEST_INITIATOR"
      ],
      "description": "The method used to create the customer request.\n\n- `DIRECT` - the client or SDKs created this customer request by calling the \"CreateCustomerRequest\" endpoint\n- `REQUEST_INITIATOR` - a customer interacted with a request initiator and caused Cash App to create a customer request.",
      "title": "RequestOriginType"
    },
    "RequestRequesterProfile": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the brand to be shown in Cash App next to payments.\n\nMin length: `1`\nMax length: `1024`"
        },
        "logo_url": {
          "type": "string",
          "format": "uri",
          "description": "URL to the image of the entity (brand or client) that is requesting permission to perform the actions on the customer request.\n\nFormats:\n- `.jpg`\n- `.jpeg`\n- `.png`\n\nMin length: `8`\nMax length: `8000`"
        }
      },
      "required": [
        "name",
        "logo_url"
      ],
      "description": "Details about the brand or client that are requesting permission to perform the actions on the customer request.",
      "title": "RequestRequesterProfile"
    },
    "RequestStatus": {
      "type": "string",
      "enum": [
        "APPROVED",
        "DECLINED",
        "PENDING",
        "PROCESSING"
      ],
      "default": "PENDING",
      "description": "Indicates if the state is approved, declined, or pending. Approved requests have grants, while pending and declined grants do not.\n\nCurrent values:\n\n- `PENDING`: The request has been created, but not responded to.\n- `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.\n- `APPROVED`: The request was approved by the customer and grants have been created for the provided actions.\n- `DECLINED`: The request was denied by the customer. No grants were created.",
      "title": "RequestStatus"
    }
  }
}