Guides Use cases API Changelog

API version reference

Moov's API versioning follows the format vYYYY.QQ.BB, where

  • YYYY is the year
  • QQ is the two-digit month for the first month of the quarter (e.g., 01, 04, 07, 10)
  • BB is the build number, starting at .00, for subsequent builds in the same quarter.

For example, v2026.01.00 is the initial release of the first quarter of 2026.

Lifecycle

Each quarter's API version is released at the start of that quarter. For example, v2026.10.00 will be released in October 2026. Once released, a version is considered stable and will only receive non-breaking changes.

When a new version is released, work begins on the next quarter's version, which is considered in development. The in development version receives new features, breaking changes, and non-breaking changes throughout the quarter. For example, when v2026.07.00 releases in July, v2026.10.00 enters in development and will eventually be available for early access.

Note - if no changes are made to the in development API version, that version will be skipped for an official release and will disappear from our public documentation.

If no API version is passed in your header request, Moov will default to v2024.01.00.

Available versions

  • v2026.10.00 (in-development)
  • v2026.07.00 (current)
  • v2026.04.00
  • v2026.01.00
  • v2025.07.00
  • v2025.04.00
  • v2025.01.00
  • v2024.01.00 (default)

The in development version of the API always represents the next quarter's API.

Setting the API version

To use a specific API version, set the X-Moov-Version header on every request:

X-Moov-Version: v2026.07.00

2026.10.00 (in-development)

  • Adds the /transfers/{transferID}/risk-outcomes endpoint. Use the endpoint to retrieve the risk rules that contributed to a transfer's risk decision.

2026.07.00

  • Adds the /product-categories endpoint which returns a read-only list of product categories from the product taxonomy
  • Adds PUT and DELETE avatar endpoints to update or delete a logo
  • Adds support for deferred payments, from 24-48 hours, in payment links and push-to-card transfers
  • Adds the /card-metadata endpoint which allows you to to look up metadata for a card without linking it to a Moov account. This endpoint requires you to provide Moov with a copy of your PCI attestation of compliance before use.
  • Removes salesTaxAmount on payment links and transfers
  • Adds amountDetail.tax to payment links and transfers
  • Adds support for surcharge fees for credit card transactions in amountDetails.surcharge in payment links and transfers
  • Adds support for tipping in amountDetails.tip in transfers and with the /accounts/{accountID}/transfer-config endpoint for payment links

2026.04.00

  • Adds resolution links. Resolution links are temporary, secure links sent to accounts to resolve requirements such as KYC verification or document uploads.
  • Adds invoices. Accounts can generate an invoice with line items to send to customers.
  • instantBankDetails replaces rtpDetails in the transfer response. In the future, instantBankDetails will also show FedNow details.

2026.01.00

Adds the instant-bank-credit payment method for real-time payments via RTP (FedNow support coming soon). While rtp-credit will continue to be supported, Moov strongly suggests moving to the instant-bank-credit payment method.

2025.07.00

  • New support tickets allow you to hand off connected account support to Moov, and Moov will respond
  • Granular capabilities allow you to only request the capabilities you need, shortening onboarding time
  • Underwriting dynamically generates based on an account's business profile and requested capabilities
  • New enriched industry taxonomies model
  • Allows Moov to create guest accounts for Tap to Pay processing

2025.04.00

  • Adds support for a terminalCard source and the card-present-payment payment method type for in-person payments.

2025.01.00

  • Updates error response status codes.

Breaking changes

  • Non-breaking changes may be added to a release even after it becomes stable.
  • Minor breaking changes may be added to a release while it's in beta. Moov attempts to minimize this as much as possible.
  • Brand new features or major breaking changes will be in the in development branch, which is typically the next future quarter's API. Moov may release new features or major breaking changes for customers who are in specific beta programs or testing various features with us.

See the breaking changes guide for more details.

Moov SDKs

Moov's official SDKs set the X-Moov-Version header automatically. Each SDK release is pinned to a specific API version — you don't need to set the header yourself.

SDK versioning

These apply to the TypeScript, PHP, Java, Python, Ruby, and .NET SDKs:

Each SDK release line targets one API version and sends it in the X-Moov-Version header for you. Prerelease SDKs (-dev.x, or -beta.x for PHP) target the API version that's in development; use them with caution.

  • Starting an integration: install the latest SDK release, which targets the current API version, v2026.07.00. For TypeScript, install the release-line tag: npm install @moovio/sdk@2026-07.
  • Finding the API version of an installed SDK: SDK version numbers don't line up with API versions, and the same API version can have different numbers in different languages. Each package records the API version it targets as a vYYYY.MM.00 string, for example openapiDocVersion in the TypeScript SDK's lib/config.js, or moovio_sdk.OPENAPI_DOC_VERSION in Python.
  • Locking it down: once your integration works, commit your lockfile so updates are deliberate. Version ranges like ^ and ~ can't hold an API version, because one API version spans several SDK version numbers. For TypeScript, update by running the same npm install @moovio/sdk@2026-07 again; for any SDK, check the installed package's API version after you update.

Moov's Go SDK follows a different versioning system. Visit the Go SDK for specific information.

Custom SDKs and direct API integrations

If you generate your own SDK from our OpenAPI specification, or call the API directly, you are responsible for setting the X-Moov-Version header.

Each OpenAPI spec includes the version it corresponds to in the info.version field. Configure your HTTP client or generated SDK to send this value as the X-Moov-Version header with every request. For example, if info.version is v2026.10.00, every request should include:

X-Moov-Version: v2026.10.00

Most OpenAPI generators do not automatically set header defaults, so you will likely need to configure this in a request interceptor, middleware, or client constructor — depending on your HTTP client or generated SDK.