Cash App Network API

openapi: 3.2.0
info:
  title: Network 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: Network API
paths: {}
webhooks:
  merchant-status-updated:
    post:
      operationId: merchant-status-updated
      summary: 'Event: merchant.status.updated'
      description: "**When is this event triggered?**\n\nThis event is created whenever a merchant's status is changed. The status change can be due to do many different things:\n  - An API client-initiated action to disable / enable the merchant\n  - An asynchronous merchant registration process completing, moving the merchant from pending to active\n  - A compliance ban on the merchant, moving them to disabled"
      parameters:
      - 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: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: The type of event that occurred. `merchant.status.updated` for this event.
                event_id:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                created_at:
                  type: string
                  format: date-time
                  description: '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:
                  $ref: '#/components/schemas/WebhooksMerchantStatusUpdatedPayloadContentApplicationJsonSchemaData'
                  description: Data about the merchant that had a status change.
              required:
              - type
              - event_id
              - created_at
              - data
      tags:
      - Network API
  grant-created:
    post:
      operationId: grant-created
      summary: 'Event: grant.created'
      description: '**When is this event triggered?**


        This event is created whenever a grant is created. This is caused by a customer request being approved.'
      parameters:
      - 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: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: The type of event that occurred. `grant.created` for this event.
                event_id:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                created_at:
                  type: string
                  format: date-time
                  description: '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:
                  $ref: '#/components/schemas/WebhooksGrantCreatedPayloadContentApplicationJsonSchemaData'
                  description: Data about the grant that was created.
              required:
              - type
              - event_id
              - created_at
              - data
      tags:
      - Network API
  grant-status-updated:
    post:
      operationId: grant-status-updated
      summary: 'Event: grant.status.updated'
      description: "**When is this event triggered?**\n\nThis event is created whenever a grant's status is changed. The status change can be due to a couple different things:\n  - An API client-initiated action to create a payment or revoke a grant (all opertions which consume a one-time use grant)\n  - A customer revoking an extended-use grant"
      parameters:
      - 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: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: The type of event that occurred. `grant.status.updated` for this event.
                event_id:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                created_at:
                  type: string
                  format: date-time
                  description: '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:
                  $ref: '#/components/schemas/WebhooksGrantStatusUpdatedPayloadContentApplicationJsonSchemaData'
                  description: Data about the grant that had a status change.
              required:
              - type
              - event_id
              - created_at
              - data
      tags:
      - Network API
  customer-created:
    post:
      operationId: customer-created
      summary: 'Event: customer.created'
      description: '**When is this event triggered?**


        This event is created whenever a new Cash App Pay customer is created. A new Cash App Pay customer is created when a Cash App user approves a client''s Cash App Pay request for the first time. This event allows clients to detect customers who are using a client''s Cash App Pay integration for the first time.'
      parameters:
      - 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: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: The type of event that occurred. `customer.created` for this event.
                event_id:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                created_at:
                  type: string
                  format: date-time
                  description: '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:
                  $ref: '#/components/schemas/WebhooksCustomerCreatedPayloadContentApplicationJsonSchemaData'
                  description: Data about the Customer that was created.
              required:
              - type
              - event_id
              - created_at
              - data
      tags:
      - Network API
  customer-updated:
    post:
      operationId: customer-updated
      summary: 'Event: customer.updated'
      description: "**When is this event triggered?**\n\nThis event is created whenever a Cash App Pay customer is updated. The `customer.updated` event can be triggered when:\n  - A customer updates their Cashtag.\n  - A customer approves a request with a `customer_metadata.reference_id` attribute. Upon approval of the request, the customer's `reference_id` attribute is updated.\n\n  > **Note:** If the `customer_metadata.reference_id` is the same as the customer's current `reference_id`, the customer will not be updated and the event will not be triggered."
      parameters:
      - 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: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: The type of event that occurred. `customer.updated` for this event.
                event_id:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                created_at:
                  type: string
                  format: date-time
                  description: '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:
                  $ref: '#/components/schemas/WebhooksCustomerUpdatedPayloadContentApplicationJsonSchemaData'
                  description: Data about the Customer that was updated.
              required:
              - type
              - event_id
              - created_at
              - data
      tags:
      - Network API
  customer-deleted:
    post:
      operationId: customer-deleted
      summary: 'Event: customer.deleted'
      description: '**When is this event triggered?**


        This event is created whenever a Cash App Pay customer is deleted. The `customer.deleted` event will be triggered when a customer account is deleted by Cash App.'
      parameters:
      - 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: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: The type of event that occurred. `customer.deleted` for this event.
                event_id:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                created_at:
                  type: string
                  format: date-time
                  description: '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:
                  $ref: '#/components/schemas/WebhooksCustomerDeletedPayloadContentApplicationJsonSchemaData'
                  description: Data about the Customer that was deleted.
              required:
              - type
              - event_id
              - created_at
              - data
      tags:
      - Network API
  payment-status-updated:
    post:
      operationId: payment-status-updated
      summary: 'Event: payment.status.updated'
      description: "**When is this event triggered?**\n\nThis event is created whenever a payment status is changed. The status change can be due to a couple different things:\n  - An API client-initiated action to void or capture the payment\n  - A payment auto-voiding after 7 days of not being captured"
      parameters:
      - 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: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: The type of event that occurred. `payment.status.updated` for this event.
                event_id:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                created_at:
                  type: string
                  format: date-time
                  description: '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:
                  $ref: '#/components/schemas/WebhooksPaymentStatusUpdatedPayloadContentApplicationJsonSchemaData'
                  description: Data about the payment that had a status change.
              required:
              - type
              - event_id
              - created_at
              - data
      tags:
      - Network API
  refund-status-updated:
    post:
      operationId: refund-status-updated
      summary: 'Event: refund.status.updated'
      description: "**When is this event triggered?**\n\nThis event is created whenever a refund status is changed. The status change can be due to a couple different things:\n  - An API client-initiated action to void or capture the refund\n  - A refund auto-voiding after 7 days of not being captured"
      parameters:
      - 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: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: The type of event that occurred. `refund.status.updated` for this event.
                event_id:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                created_at:
                  type: string
                  format: date-time
                  description: '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:
                  $ref: '#/components/schemas/WebhooksRefundStatusUpdatedPayloadContentApplicationJsonSchemaData'
                  description: Data about the refund that had a status change.
              required:
              - type
              - event_id
              - created_at
              - data
      tags:
      - Network API
  dispute-created:
    post:
      operationId: dispute-created
      summary: 'Event: dispute.created'
      description: '**When is this event triggered?**


        This event is created whenever a dispute is created. This is caused by a customer filing a dispute concerning a payment collected by a merchant managed by this API client.'
      parameters:
      - 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: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: The type of event that occurred. `dispute.created` for this event.
                event_id:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                created_at:
                  type: string
                  format: date-time
                  description: '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:
                  $ref: '#/components/schemas/WebhooksDisputeCreatedPayloadContentApplicationJsonSchemaData'
                  description: Data about the dispute that was created.
              required:
              - type
              - event_id
              - created_at
              - data
      tags:
      - Network API
  dispute-status-updated:
    post:
      operationId: dispute-status-updated
      summary: 'Event: dispute.status.updated'
      description: "**When is this event triggered?**\n\nThis event is created whenever a dispute's state is updated. This can be caused by a variety of things:\n  - An API client-driven change where the dispute is accepted or challenged\n  - Cash App Pay making a final decision on a dispute"
      parameters:
      - 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: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: The type of event that occurred. `dispute.status.updated` for this event.
                event_id:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                created_at:
                  type: string
                  format: date-time
                  description: '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:
                  $ref: '#/components/schemas/WebhooksDisputeStatusUpdatedPayloadContentApplicationJsonSchemaData'
                  description: Data about the dispute that was updated.
              required:
              - type
              - event_id
              - created_at
              - data
      tags:
      - Network API
components:
  schemas:
    Category:
      type: string
      description: The merchant category code associated with the entity. Values are from the [ISO-18245 specification](https://www.iso.org/standard/33365.html).
      title: Category
    PaymentEnrichmentsInitiationActor:
      type: string
      enum:
      - CUSTOMER
      - MERCHANT
      description: 'The party who initiated the payment.


        - `CUSTOMER`

        - `MERCHANT`'
      title: PaymentEnrichmentsInitiationActor
    WebhooksGrantCreatedPayloadContentApplicationJsonSchemaData:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier provided by Cash App for the grant.
        object:
          $ref: '#/components/schemas/WebhooksGrantCreatedPayloadContentApplicationJsonSchemaDataObject'
          description: A snapshot of the grant immediately after the grant was created.
        type:
          type: string
          description: The resource type contained in the `object` field. For this event, it is `grant`.
      required:
      - id
      - object
      - type
      description: Data about the grant that was created.
      title: WebhooksGrantCreatedPayloadContentApplicationJsonSchemaData
    WebhooksCustomerUpdatedPayloadContentApplicationJsonSchemaDataObject:
      type: object
      properties:
        customer:
          $ref: '#/components/schemas/Customer'
      required:
      - customer
      description: A snapshot of the customer immediately after the customer was updated.
      title: WebhooksCustomerUpdatedPayloadContentApplicationJsonSchemaDataObject
    WebhooksGrantStatusUpdatedPayloadContentApplicationJsonSchemaData:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier provided by Cash App for the grant.
        object:
          $ref: '#/components/schemas/WebhooksGrantStatusUpdatedPayloadContentApplicationJsonSchemaDataObject'
          description: A snapshot of the grant immediately after the grant's status changed.
        type:
          type: string
          description: The resource type contained in the `object` field. For this event, it is `grant`.
      required:
      - id
      - object
      - type
      description: Data about the grant that had a status change.
      title: WebhooksGrantStatusUpdatedPayloadContentApplicationJsonSchemaData
    Payment:
      type: object
      properties:
        id:
          type: string
          description: 'Unique identifier for this payment issued by Cash App.


            Min length: `1`

            Max length: `128`'
        amount:
          type: integer
          description: 'The amount of money to collect, in the lowest denomination of currency on the payment. This is the _original_ amount authorized when the payment was created.


            Min value: `1`'
        net_amount:
          type: integer
          description: 'The amount remaining after refunds and voided payments are deducted from the amount field. The amount will be in the lowest denomination of the currency on the payment.

            This is the amount that will be shown to the customer in their Cash App account.



            Min value: `0`'
        captured_amount:
          type: integer
          description: 'The amount of money on this payment that has been allocated for settlement. The amount will be in the lowest denomination of the currency on the payment.


            Min value: `0`'
        voided_amount:
          type: integer
          description: 'The amount of money on this payment that is no longer authorized and has been released back to the customer. The amount will be in the lowest denomination of the currency on the payment.


            Min value: `0`'
        refunded_amount:
          type: integer
          description: 'Sum of captured refunds in the lowest denomination of currency on the payment.


            Min value: `0`'
        currency:
          $ref: '#/components/schemas/Currency'
        customer_id:
          type: string
          description: 'ID of the customer that sent this payment.


            Min length: `1`

            Max length: `128`'
        merchant_id:
          type: string
          description: 'ID of the merchant that received this payment.


            Min length: `1`

            Max length: `128`'
        grant_id:
          type: string
          description: 'ID of the grant to used to create this payment.


            Min length: `1`

            Max length: `256`'
        status:
          $ref: '#/components/schemas/PaymentStatus'
          description: 'The step of the payment processing lifecycle that this payment is currently at.


            - `AUTHORIZED`

            - `CAPTURED`

            - `VOIDED`

            - `DECLINED`'
        created_at:
          type: string
          format: date-time
          description: When this payment was created, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: When this payment was last updated, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        capture_before:
          type: string
          format: date-time
          description: When this payment should be captured by, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        refund_ids:
          type: array
          items:
            type: string
          description: 'A list of one or more IDs associated with refunds issued for this payment.


            Min array length: `1`

            Min length of IDs: `1`

            Max length of IDs: `128`'
        reference_id:
          type: string
          description: 'A user-defined identifier for this payment, typically used to associate the payment with a record in an external system.


            Min length: `1`

            Max length: `1024`'
        metadata:
          $ref: '#/components/schemas/Metadata'
        enrichments:
          $ref: '#/components/schemas/PaymentEnrichments'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: 'If the payment was declined, contains a list of the reasons why it was declined.


            Min number of items: `1`'
        fee_amount:
          type: number
          format: double
          description: The total fee amount that was charged to the merchant for processing this payment.
        fee_rate:
          $ref: '#/components/schemas/FeeRate'
          description: The breakdown of the fee that was charged to the merchant for processing this payment.
        authorization_updates:
          type: array
          items:
            $ref: '#/components/schemas/Authorization'
          description: "A list of authorization update attempts associated with this payment, sorted in chronological order.\n\nNote: This field contains only the authorization update attempts, so this field will be empty when \nthe payment is first created (even though the amount is authorized in this flow, it is not an update)."
      required:
      - id
      - amount
      - net_amount
      - captured_amount
      - voided_amount
      - refunded_amount
      - currency
      - customer_id
      - merchant_id
      - grant_id
      - status
      - created_at
      - updated_at
      title: Payment
    Country:
      type: string
      enum:
      - US
      description: 'Indicates the country associated with an entity. Values are from the [ISO-3166 Alpha-2](https://www.iso.org/iso-3166-country-codes.html) specification.


        Current values:


        - `US`: United States of America'
      title: Country
    WebhooksPaymentStatusUpdatedPayloadContentApplicationJsonSchemaDataObject:
      type: object
      properties:
        payment:
          $ref: '#/components/schemas/Payment'
      required:
      - payment
      description: A snapshot of the payment data immediately after the payment's status changed.
      title: WebhooksPaymentStatusUpdatedPayloadContentApplicationJsonSchemaDataObject
    Merchant:
      type: object
      properties:
        id:
          type: string
          description: 'A unique identifier for the merchant issued by Cash App.


            Min length: `1`

            Max length: `128`'
        brand_id:
          type: string
          description: 'ID of the brand associated with this merchant.


            Min length: `1`

            Max length: `128`'
        name:
          type: string
          description: 'The name of the individual or business entity associated with the merchant.


            Min length: `1`

            Max length: `1024`'
        country:
          $ref: '#/components/schemas/Country'
        currency:
          $ref: '#/components/schemas/Currency'
        category:
          $ref: '#/components/schemas/Category'
        reference_id:
          type: string
          description: 'A user-defined identifier for this merchant, typically used to associate the merchant with a record in an external system. Independent from the [brand reference_id](https://developers.cash.app/docs/api/network-api/operations/create-a-brand#request-body).


            Min length: `1`

            Max length: `1024`'
        status:
          $ref: '#/components/schemas/MerchantStatus'
          description: 'Whether or not this merchant can be used to accept payments or issue refunds.


            - `ACTIVE`: The merchant can accept payments or issue refunds.

            - `RISK_DISABLED`: Cash App Pay blocked this merchant due to them being high risk. There is no way to re-enable them programmaticaly.

            - `COMPLIANCE_DISABLED`: Cash App Pay blocked this merchant due to them not following the terms of service, Program Rules, or local laws. There is no way to re-enable them programmaticaly.

            - `CLIENT_DISABLED`: The client called the [UpdateMerchant](Network-API.v1.yaml/paths/~1merchants~1{merchant_id}/patch) endpoint and disabled this merchant, preventing it from being able to handle payments or refunds. To reverse this, call the endpoint again with the status field set to `ACTIVE`.

            - `PENDING`: The merchant is not ready to accept payments or refunds yet; the registration process is still running.'
        created_at:
          type: string
          format: date-time
          description: When this merchant was created, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: When this merchant was last updated, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        address:
          $ref: '#/components/schemas/Address'
        site_url:
          type: string
          format: uri
          description: 'The URL of the website, if this merchant is for an eCommerce site.


            Min length: `8`

            Max length: `8000`'
        

# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cash-app/refs/heads/main/openapi/cash-app-network-api-api-openapi.yml