# Versioning
source: https://developer.mastercard.com/mastercard-gateway/documentation/versioning/index.md

## Overview {#overview}

Mastercard Gateway has updated the **Mastercard Gateway API version** to [API version 100](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/index.md) (v100). v100 is the first API version that supports **backward-compatible changes**.

If you integrate with v100, you can use the latest features, such as security enhancements and performance improvements that Mastercard Gateway offers.

## Mastercard Gateway API Versioning {#mastercard-gateway-api-versioning}

**v100** represents a significant improvement in our API versioning strategy. This approach enables the gateway to release enhancements, new functionalities, and fixes that merchants can seamlessly use without requiring frequent API version upgrades.

We have integrated the backward-compatible changes to the latest API version. A new API version will only be introduced when it is not possible to maintain backward compatibility.

The Mastercard Gateway API is versioned through **URI paths**.

### Example URI {#example-uri}

    {{host}}/api/rest/version/100/merchant/{merchantId}/agreement/{agreementId}

## Changes to the Mastercard Gateway API {#changes-to-the-mastercard-gateway-api}

As part of the strategic API modernization initiative, interactions with Mastercard Gateway will be simplified.  

Currently, we have merchant API versions **1--100** , with the oldest dating back to 2010 and many no longer in use.  

We will **discontinue outdated and unused merchant API versions**.

### Benefits of API Version Deprecation {#benefits-of-api-version-deprecation}

Deprecating Mastercard Gateway API versions will reduce:

* Support cost
* Integrator confusion
* Regression testing effort and time

### API Versions Deactivation {#api-versions-deactivation}

We will deactivate REST and NVP API versions that customers do not use.

| Gateway Region or Platform |   API Version   | Deactivation Date |
|----------------------------|-----------------|-------------------|
| All regions                | 2, 5, 6, 22, 25 | 31 January 2025   |

Note: No action required, but ensure merchants do not integrate with an API scheduled for deactivation. New merchants must integrate with **v100**.

## Potential Breaking Changes {#potential-breaking-changes}

Breaking changes occur when APIs are added or removed in ways that disrupt existing integrations.  

Any integration to v100 must accommodate future **non-breaking changes** for seamless compatibility.

### Non-breaking {#non-breaking}

* Adding an API interface to a service
* Adding an HTTP binding to a method
* Adding a method to an API interface
* Adding an output-only resource field

### Breaking {#breaking}

* Removing an operation
* Adding a required URL parameter

### Non-breaking {#non-breaking}

* Adding a field to a request message

### Breaking {#breaking}

* Changing an HTTP verb
* Adding a required header
* Removing a header
* Adding a required field
* Removing a field
* Renaming a field
* Changing a field from optional to required
* Changing the type of a field
* Making an existing field more restrictive by:
  * Changing validations
  * Reducing numeric min-max range
  * Reducing string max length
  * Increasing string min length
  * Removing a value from an enum
  * Updating a field pattern to make it more restrictive

### Non-breaking {#non-breaking}

* Adding a field to a response message

### Breaking {#breaking}

* Changing or adding an HTTP status response code
* Removing a header
* Removing a field
* Renaming a field
* Changing a field from required to optional
* Changing the type of a field
* Making an existing field less restrictive by:
  * Changing validations
  * Extending numeric min-max range
  * Increasing string max length
  * Decreasing string min length
  * Adding a value to an enum