openapi: 3.2.0 info: title: Network Customers API version: 1.0.0 servers: - url: https://api.cash.app/network/v1 description: Production - url: https://sandbox.api.cash.app/network/v1 description: Sandbox tags: - name: customers paths: /customers: get: operationId: list-customers summary: List customers description: 'Returns a list of all customers matching the given query parameters who have ever authorized this client to take an action on their account. **This endpoint is rate limited to 50 QPS.** Scopes: `CUSTOMERS_READ`' tags: - customers parameters: - name: cursor in: query description: A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. required: false schema: type: string - name: limit in: query description: Maximum number of customers to return. required: false schema: type: integer default: 50 - name: cashtag in: query description: Filters results to only include customers with a matching Cashtag. required: false schema: type: string - name: Accept in: header required: true schema: type: string - name: X-Region in: header required: true schema: type: string - name: X-Signature in: header required: true schema: type: string - name: User-Agent in: header required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Customers_list-customers_Response_200' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /customers/{customer_id}: get: operationId: retrieve-customer summary: Retrieve customer description: 'Retrieves a customer by its ID. **This endpoint is not rate limited.** Scopes: `CUSTOMERS_READ`' tags: - customers parameters: - name: customer_id in: path required: true schema: type: string - name: Accept in: header required: true schema: type: string - name: X-Region in: header required: true schema: type: string - name: X-Signature in: header required: true schema: type: string - name: User-Agent in: header required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Customers_retrieve-customer_Response_200' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /customers/{customer_id}/grants/{grant_id}: get: operationId: retrieve-customer-grant summary: Retrieve customer grant description: 'Retrieves a customer grant by the ID of the customer that approved it and its own ID. **This endpoint is not rate limited.** Scopes: `GRANTS_READ`' tags: - customers parameters: - name: customer_id in: path required: true schema: type: string - name: grant_id in: path required: true schema: type: string - name: Accept in: header required: true schema: type: string - name: X-Region in: header required: true schema: type: string - name: X-Signature in: header required: true schema: type: string - name: User-Agent in: header required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Customers_retrieve-customer-grant_Response_200' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /customers/{customer_id}/grants: get: operationId: list-customer-grants summary: List customer grants description: 'Returns a list of all customer grants for a given customer that match the provided query parameters. **This endpoint is rate limited to 250 QPS.** Scopes: `GRANTS_READ`' tags: - customers parameters: - name: customer_id in: path required: true schema: type: string - name: cursor in: query description: A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. required: false schema: type: string - name: limit in: query description: Maximum number of customer grants to return required: false schema: type: integer default: 50 - name: Accept in: header required: true schema: type: string - name: X-Region in: header required: true schema: type: string - name: X-Signature in: header required: true schema: type: string - name: User-Agent in: header required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Customers_list-customer-grants_Response_200' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /customers/{customer_id}/grants/{grant_id}/revoke: post: operationId: revoke-customer-grant summary: Revoke customer grant description: "Revokes a customer grant, rendering it unusable. Other endpoints will no longer be able to use the grant to perform its associated action.\n\n \nYou cannot un-revoke a grant. Use with caution.\n\n\n**This endpoint is not rate limited.**\n\nScopes: `GRANTS_WRITE`" tags: - customers parameters: - name: customer_id in: path required: true schema: type: string - name: grant_id in: path required: true schema: type: string - name: Accept in: header required: true schema: type: string - name: X-Region in: header required: true schema: type: string - name: X-Signature in: header required: true schema: type: string - name: User-Agent in: header required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Customers_revoke-customer-grant_Response_200' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: LinkAccountAction: type: object properties: type: $ref: '#/components/schemas/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 Customers_revoke-customer-grant_Response_200: type: object properties: grant: $ref: '#/components/schemas/Grant' required: - grant title: Customers_revoke-customer-grant_Response_200 Customers_retrieve-customer-grant_Response_200: type: object properties: grant: $ref: '#/components/schemas/Grant' required: - grant title: Customers_retrieve-customer-grant_Response_200 Action: oneOf: - $ref: '#/components/schemas/OneTimePaymentAction' - $ref: '#/components/schemas/OnFilePaymentAction' - $ref: '#/components/schemas/OnFileDepositAction' - $ref: '#/components/schemas/LinkAccountAction' 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. - `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.' title: Channel Customer: type: object properties: id: type: string description: 'Unique identifier for this customer issued by Cash App. Min length: `1` Max 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). Min length: `1` Max length: `1024`' reference_id: type: string description: A user-defined identifier for this customer, typically used to associate the customer with a record in an external system. This value can be provided via the `CustomerRequest.customer_metadata.reference_id` attribute. Upon approval of the CustomerRequest, a corresponding customer resource is created with the `reference_id` attribute. required: - id - cashtag title: Customer Customers_retrieve-customer_Response_200: type: object properties: customer: $ref: '#/components/schemas/Customer' required: - customer title: Customers_retrieve-customer_Response_200 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 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 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 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 OneTimePaymentActionType: type: string enum: - ONE_TIME_PAYMENT description: The type of the action (`ONE_TIME_PAYMENT`). title: OneTimePaymentActionType OnFileDepositActionType: type: string enum: - ON_FILE_DEPOSIT description: The type of the action (`ON_FILE_DEPOSIT`). title: OnFileDepositActionType ErrorResponse: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' description: 'A list of errors that occurred while processing the request. Min number of items: `1`' required: - errors title: ErrorResponse OneTimePaymentAction: type: object properties: amount: type: integer description: 'Amount to charge the customer, in the lowest unit of the associated currency. Min value: `1`' currency: $ref: '#/components/schemas/Currency' scope_id: type: string description: '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`' type: $ref: '#/components/schemas/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. Note the following restrictions when using this action: - If no amount is provided to the action, the payment charged may be **any** amount. - If `amount` is provided, `currency` must be provided too (and vice versa).' title: OneTimePaymentAction LinkAccountActionType: type: string enum: - LINK_ACCOUNT description: The type of the action (`LINK_ACCOUNT`). title: LinkAccountActionType OnFilePaymentActionType: type: string enum: - ON_FILE_PAYMENT default: ON_FILE_PAYMENT description: The type of the action (`ON_FILE_PAYMENT`). title: OnFilePaymentActionType 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. 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.' title: GrantStatus Grant: type: object properties: id: type: string description: 'Unique identifier for this grant issued by Cash App. Min length: `1` Max length: `256`' customer_id: type: string description: 'ID of the customer that approved this grant. Min length: `1` Max 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. Min length: `1` Max length: `128`' action: $ref: '#/components/schemas/Action' status: $ref: '#/components/schemas/GrantStatus' description: '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.' type: $ref: '#/components/schemas/GrantType' description: Describes whether this grant can be only be used once (`ONE_TIME`) or repeatedly (`EXTENDED`). channel: $ref: '#/components/schemas/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. The 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 Customers_list-customers_Response_200: type: object properties: customers: type: array items: $ref: '#/components/schemas/Customer' description: List of customers matching the given query parameters. cursor: type: string description: The pagination cursor to be used in a subsequent request. If empty, this is the final response. required: - customers title: Customers_list-customers_Response_200 OnFileDepositAction: type: object properties: type: $ref: '#/components/schemas/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. 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`' 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 OnFilePaymentAction: type: object properties: scope_id: type: string description: '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`' type: $ref: '#/components/schemas/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 Customers_list-customer-grants_Response_200: type: object properties: grants: type: array items: $ref: '#/components/schemas/Grant' description: List of customer grants matching the given query parameters cursor: type: string description: The pagination cursor to be used in a subsequent request. If empty, this is the final response. required: - grants title: Customers_list-customer-grants_Response_200