Overview

At MoneyGram, we continue to enhance our API as we introduce new features and expand our service coverage. This section outlines how we manage API versioning so you can understand what to expect. These policies apply to our REST endpoints and webhook subscriptions, both in sandbox and production environments.

Breaking Changes & Versioning API

A breaking change is defined as: any modification that requires users (clients) to change their code in order for it to continue working correctly with the API. These changes "break" backward compatibility, meaning applications built with a previous version of the API will no longer function as expected without adjustments. When such changes occur, we increment the version of the affected API to avoid disrupting existing integrations.

Common Examples of Breaking Changes:

Removing a field from a response object.
Renaming or deleting an endpoint.
Changing the data type of a field (e.g. from string to integer).
Altering the structure of a response in a way that existing clients don’t expect.
Modifying authentication or authorization requirements.

Note: not all API endpoints are versioned simultaneously. If a breaking change affects a specific endpoint, our documentation will clearly outline which API calls are compatible and should be used together

Extensible Changes

Extensible changes (also called non-breaking or additive changes) to an API are updates that enhance or expand the API’s capabilities without breaking existing client implementations. These changes maintain backward compatibility, meaning existing integrations will continue to work as expected, even if they don't use the new features.

Common Examples of Extensible Changes:

Adding new optional fields to a request and response.
Introducing new endpoints without altering existing ones.
Adding new query parameters that are optional.
Expanding enumerated values
Expanding field label values and other associated meta-data
Including new relationships or embedded resources in a data model

Note: To accommodate these updates, we recommend that clients architect their integrations flexibly.

Deprecating APIs

From time-to-time MoneyGram may have to deprecate old versions of API. MoneyGram will provide formal notice 6 months in advance.

Deprecating APIs refers to the process of phasing out an API or specific parts of an API (such as an endpoint, field, or version) with the intention of eventually removing or disabling them. It serves as a formal warning to developers that the feature is outdated and should no longer be used in new development.

Conditions of Deprecating APIs:

Announcement & grace period: The API provider will provide 6 months to deprecate the API and will provide high-level business justification (subject to Regulatory Change)
Continued support: Deprecated features may still function temporarily, but they won’t receive updates or fixes.
Recommended alternatives: The provider typically offers a newer version or approach to replace the deprecated functionality.

Regulatory Changes

Occasionally MoneyGram may have to make changes to the APIs in order to meet regulatory need. These modifications to the APIs could be: a) breaking changes; b) extensible changes; or c) involve a deprecation of an API. MoneyGram endeavour to give impacted clients as much advance notice as possible and will partner with client to adopt the changes.