Versioning
Overview
Since the release 24.8, we have 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.
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 |
|
| Breaking |
|
|
| Request | Non-breaking |
|
| Breaking |
|
|
| Response | Non-breaking |
|
| Breaking |
|
Test for breaking changes with chaotic responses
You can evaluate the API changes that generate chaotic responses and break an integration.
Chaotic responses may include random data elements and sequencing changes that your integration does not anticipate, however, these changes are valid non-breaking and should not disrupt your integration's functionality. This lets you verify that your integration remains compatible with future API versions.
Chaotic response FAQs
- What are the preconditions to use chaotic responses?
The preconditions to use chaotic responses are as follows:
- Chaotic responses apply only to REST-JSON requests.
- They are not designed for NVP requests.
- They are available only for TEST merchants.
- When can integrators use the Chaos Generator tool?
The Chaos Generator tool is available now for use. The integrators can evaluate their current integrations using chaotic responses to verify if their API response parser can handle unexpected responses in a non-breaking manner. The response parser ignores tags that are not required.
- How are chaotic responses enabled?
To enable chaotic responses:
- Enable the header name
X-MC-Chaotic-Responsein the list of headers that are sent in the request. - This header does not require a value and enables chaotic responses, that is, it allows the injection of chaos nodes in the response body. Only the header name must be present in the headers sent in the request.
The request header is
X-MC-Chaotic-Response.The response header is
"X-MC-Chaotic-Response-<12 last characters of an UUID>".For more information, see the chaotic response testing steps.
- Enable the header name
- Are there pre-built Postman examples for the Chaos Generator?
Yes, Postman collection and environment are available to aid testing. You can download them from the Downloads page.
- Does Mastercard Gateway offer support for changes required after chaos testing?
Contact the Mastercard Gateway support team if you need support to make changes after chaos testing by opening a project with the Mastercard Gateway Implementation team.