Versioning

Overview

Mastercard Gateway has updated the WS-API version to API version 100 (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 the Mastercard Gateway offers.

Gateway API versioning

v100 represents a significant improvement in our API versioning strategy. This approach enables us to release enhancements, new functionalities, and fixes that customers can seamlessly use without requiring frequent API version upgrades. We have integrated the backward-compatible changes to the latest API version. We will introduce a new API version only when it is not possible to maintain backward compatibility.

The Gateway API is versioned through URI paths.

Example URI


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

Planned changes to the gateway API

As part of the strategic API modernization initiative, we will simplify interactions with the Mastercard Gateway. Currently, we have merchant API versions 1-100, with the oldest version dating back to 2010 and many that are no longer in use. We will discontinue the outdated and unused merchant API versions.

Benefits of API versions deprecation

The deprecation of gateway API versions will reduce:

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

API versions deactivation

We will deactivate the REST and NVP API versions that the customers are not using at present.

Gateway Region or Platform	API version	Deactivation date
All regions	2,5,6,22,25	31 January 2025

There is no action required, however, ensure that your merchants do not integrate with an API that is scheduled for deactivation. New merchants must integrate with the latest API, v100.

Breaking changes

In breaking changes, we add or delete APIs that break any pre-existing integration. Any API integration to v100 must be designed to accommodated future non-breaking changes, ensuring seamless compatibility and minimal disruption. Here is the list of potential breaking and non-breaking changes.

Resource	API compatibility	Change
API	Non-breaking	Adding an API interface to an API service. Adding an HTTP binding to a method. Adding a method to an API interface. Adding an output-only resource field.
API	Breaking	Removing an operation. Adding a required URL parameter.
Request	Non-breaking	Adding a field to a request message.
Request	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 a numeric, min-max range. Reducing a string max length. Increasing a string min length. Removing a value from an enum. Updating a field pattern to make it more restrictive.
Response	Non-breaking	Adding a field to a response message.
Response	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 a numeric, min-max range. Increasing a string max length. Decrease a string min length. Adding a value to an enum.