Technical GuidesAPI FundamentalsRequests

API Versioning

API Versions

Customer Request API

Current Version: v1

API Versions:

  • v1
    • Status: Active; under continued development
    • Support Window (subject to change): January 1st, 2022 - March 1st, 2027
    • Accepting new developers

Network API

Current Version: v1

API Versions:

  • v1

    • Status: Active; under continued development
    • Support Window (subject to change): January 1st, 2022 - March 1st, 2027
    • Accepting new developers

  • v0

    • Status: Deprecated
    • Support Window: August 1st, 2020 - December 31st, 2022
    • Not accepting new developers

Management API

Current Version: v1

API Versions:

  • v1
    • Status: Active; under continued development
    • Support Window (subject to change): January 1st, 2022 - March 1st, 2027
    • Accepting new developers

Version Statuses

API Versions can be in one of 5 statuses:

  • Active: The API is actively serving traffic and receiving new features from patch updates
  • In development: The API is currently being built and is not available for public use
  • Maintenance: The API is actively serving traffic, but is no longer receiving new features
  • Deprecated: The API is within a year of being retired, and should no longer be adopted by new integrations. Existing integrations should plan to migrate to a newer API version.
  • Retired: The API is no longer serving traffic.

Support window refers to the period in which the API will serve traffic.

How to select an API version

The Cash App Pay API uses path-based versioning. Every API call is required to specify a version, which can be done by providing it in the URL path after the name of the API suite you’re calling:

Network API

Format: https://api.cash.app/network/v<Major.Minor>
Example: https://api.cash.app/network/v1

Customer Request API

Format: https://api.cash.app/customer-request/v<Major.Minor>
Example: https://api.cash.app/customer-request/v1

Each API suite is versioned independently.

Types of changes between versions

There are 3 types of changes Cash App Pay makes to the API, some of which are versioned:

  • Major (breaking) changes
  • Minor changes
  • Patches

Major Version Changes

Major versions introduce new features or functionality in a non-backwards-compatible way, and / or remove existing functionality. They require modifying business logic in the integration to adopt.

Examples of changes in major version updates:

  • Removing an endpoint
  • Removing a field from a request or response
  • Making a response field optional that was previously required
  • Removing a country code from the list of supported countries

Minor Version Changes

Minor versions introduce new features or functionality that are generally backwards-compatible, but may require modifying a small amount of business logic in the integration.

Examples of changes in minor version updates:

  • Adding a new country code to the list of supported countries
  • Adding a new state to a resource with a state machine (for example, a new payment state)

Patches

Patches introduce new features or functionality that are guaranteed to be 100% backwards-compatible with existing integrations. Patches are non-versioned, and will routinely be applied by the Cash App Pay engineering team.

Examples of patches:

  • Adding a new “notes” field to payments that allows an API client to add details about a payment that are shown in the Cash App mobile application
  • Adding a new endpoint for listing customer requests