Cash App Fee Plans API

openapi: 3.2.0
info:
  title: Network Fee Plans 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: feePlans
paths:
  /fee-plans/{fee_plan_id}:
    get:
      operationId: retrieve-fee-plan
      summary: Retrieve Fee Plan
      description: 'Retrieves a fee plan by its ID.


        **This endpoint is not rate limited.**


        Scopes: `FEE_PLANS_READ`'
      tags:
      - feePlans
      parameters:
      - name: fee_plan_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/Fee_Plans_retrieve-fee-plan_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'
  /fee-plans:
    get:
      operationId: list-fee-plans
      summary: List fee plans
      description: 'Returns a list of all fee plans (matching the given query parameters) associated with this client.


        **This endpoint is rate limited to 50 QPS.**


        Scopes: `FEE_PLANS_READ`'
      tags:
      - feePlans
      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 fee plans to return.
        required: false
        schema:
          type: integer
          default: 50
      - name: currency
        in: query
        description: Filters results to only include fee plans that matches the the given currency.
        required: false
        schema:
          $ref: '#/components/schemas/Currency'
      - name: status
        in: query
        description: Filters results to only include fee plans that matches the the given status.
        required: false
        schema:
          $ref: '#/components/schemas/FeePlansGetParametersStatus'
      - name: reference_id
        in: query
        description: Filters results to only include the fee plans that match the given reference ID.
        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/Fee_Plans_list-fee-plans_Response_200'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Fee_Plans_retrieve-fee-plan_Response_200:
      type: object
      properties:
        fee_plan:
          $ref: '#/components/schemas/FeePlan'
      required:
      - fee_plan
      title: Fee Plans_retrieve-fee-plan_Response_200
    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
    Fee_Plans_list-fee-plans_Response_200:
      type: object
      properties:
        fee_plans:
          type: array
          items:
            $ref: '#/components/schemas/FeePlan'
          description: List of fee plans 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.
      title: Fee Plans_list-fee-plans_Response_200
    FeePlansGetParametersStatus:
      type: string
      enum:
      - ACTIVE
      - DISABLED
      default: ACTIVE
      title: FeePlansGetParametersStatus
    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
    Metadata:
      type: object
      additionalProperties:
        type: string
      description: '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.'
      title: Metadata
    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
    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
    FeeRate:
      type: object
      properties:
        basis_points:
          type: integer
          description: The variable fee charged for processing the payment expressed as 1/100th of a percentage.
        fixed_amount:
          type: integer
          description: "The amount charged for processing the payment, in the lowest denomination of currency on the payment.\n **Note: The currency for the fee is found on the fee plan.**"
      description: A fee rate contains the components of a fee charged by Cash App to partners for a given payment.
      title: FeeRate
    FeePlan:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier for the fee plan issued by Cash App.
        rate:
          $ref: '#/components/schemas/FeeRate'
        currency:
          $ref: '#/components/schemas/Currency'
        status:
          type: string
          description: 'The state is used to determine whether or not this fee plan is currently in use.

            - `ACTIVE`

            - `DISABLED`'
        reference_id:
          type: string
        metadata:
          $ref: '#/components/schemas/Metadata'
        description:
          type: string
          description: A free-form text field that stores information associated with the fee plan.
        created_at:
          type: string
          format: date-time
          description: When this fee plan was created, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: When this fee plan was last updated, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
      required:
      - id
      - rate
      - currency
      - status
      - created_at
      - updated_at
      description: The full fee plan that PSPs can use to set the buy rates for specific merchants.
      title: FeePlan