Skip to main content

API lifecycle

This guide explains how Vipps MobilePay manages API versions, deprecations, and changes to help you maintain stable integrations.

Versioning​

Our APIs follow Semantic Versioning standards:

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes
  • MINOR version when you add functionality in a backwards compatible manner
  • PATCH version when you make backwards compatible bug fixes

Version numbers in endpoint URIs​

API versions are included directly in the endpoint path using only the major version number:

  • GET:/someapi/v1/some/more/path
  • GET:/someapi/v2/some/more/path

Example: When API version 2.3.4 is released, you'll use /v2/ in the endpoint path.

Version lifecycle​

APIs evolve over time. Keep your applications updated with the latest versions for optimal performance and new features.

Major version​

A major version is officially supported until the date when it becomes deprecated.

Major versions introduce breaking changes that are incompatible with previous versions. See Deprecation notice for details about the deprecation process.

Minor version​

A minor version is automatically superseded by a newer minor version. If a customer uses version 2.1.0, that version is automatically superseded when version 2.2.0 is available. There will be no bug fixes or other improvements to a minor version that has been superseded.

We expect you to update to the latest minor version within 30 days.

Patch version​

A patch version fixes one or more small problems, such as correcting a small bug, so the API works as intended and documented in the first place.

We expect you to update to the latest patch within 30 days.

Deprecation notice​

Minimum notice period: 4 months

When we deprecate an API or major version, we provide at least four months notice before the deprecation date.

Notification channels​

We use multiple channels to ensure you're informed about deprecations:

1. Technical updates newsletter​

Review technical updates for deprecation announcements as soon as decisions are made. Strongly recommended for all developers.

2. Personal contact​

For partners and key accounts: Your partner manager or Key Account Manager (KAM) will contact you directly about deprecations.

3. Email notifications​

We attempt to email the technical contact registered for your merchant account. If no technical contact is registered, we'll contact the main account contact.

Keep contact information current

Please make sure we have the correct contact information. If you need to send updates, please contact us at help.vippsmobilepay.com.

APIs​

The API version is included in the path: v1, v2, etc. Only the major version is specified.

API documentation​

When the API specifications are updated, we version it according to the mentioned versioning standards.

Backwards compatibility​

We strive to improve existing APIs while also maintaining backwards compatibility.

We consider the following changes to be backwards compatible:

Adding an optional field to a request​

An optional parameter for a request is considered a backwards compatible change. The caller may choose to send the new, optional parameter, but there is no obligation to do so. There is no change in the API's functionality if the new, optional parameter is omitted.

The parameter can be added as part of the request body, as a URL parameter, or an HTTP header field.

Some optional parameters may offer additional or improved functionality, but the API will never offer less than before the optional parameter was added.

Example​

We may add a msisdn field to support international phone numbers, in addition to Norwegian-only phone numbers:

Version 2.0.0:

  "customerInfo": {
    "mobileNumber": 4712345678
  }

Version 2.1.0:

  "customerInfo": {
    "mobileNumber": 12345678,
    "msisdn": 4712345678
  }

Adding an optional field to a response​

An optional parameter for a response is considered a backwards compatible change.

The parameter can be added as part of the response body or an HTTP header field.

It is the caller's responsibility to manage the response in a way that correctly handles new, optional parameters. This is normally done automatically, but we want to explicitly mention this.

Example of option field​

We may add a type field to the address object:

Version 2.0.0:

"address": {
  "addressLine1": "Robert Levins gate 5",
  "city": "Oslo",
  "postCode": "0154",
  "country": "Norway"
  }

Version 2.1.0:

"address": {
  "addressLine1": "Robert Levins gate 5",
  "city": "Oslo",
  "postCode": "0154",
  "country": "Norway",
  "type": "business"
  }

Adding a new enum value​

The value may be added either in the request or in the response.

Response parsing must be robust: Ignore any unknown fields or enum values received as part of API responses.

Relaxing some constraints on an existing request parameter​

For example, making it optional.

Adding a new response parameter to the API response​

Response parsing must be robust, and able to handle new parameters.

The parameter can be added as part of the request body, as a URL parameter, or an HTTP header field.

Changing the order in which parameters are returned in existing API responses​

Response parsing must be robust.

Correcting faulty functionality in edge cases​

If the API has offered unintended, undocumented functionality, we consider it a backwards compatible change to correct it.

Breaking changes​

Changes that are incompatible with previous versions of an API requires a new major version. This means a bump from 2.3.4 to 3.0.0.

The API endpoints will also get a new version parameter in the path, for example: from v2 to v3.

Breaking changes include:

Changing the properties of an object​

A change in the format for country from the full name of the country (Norway) to ISO 3166 (NO) is considered a breaking change, as it requires a change in code that uses the API.

Version 2.0.0:

"address": {
  "addressLine1": "Robert Levins gate 5",
  "city": "Oslo",
  "postCode": "0154",
  "country": "Norway"
  }

Version 3.0.0:

"address": {
  "addressLine1": "Robert Levins gate 5",
  "city": "Oslo",
  "postCode": "0154",
  "country": "NO",
  }

If the ISO 3166 country code was added as countryCode in addition to the existing country, it would be a non-breaking change, and only a minor version:

Version 2.1.0:

"address": {
  "addressLine1": "Robert Levins gate 5",
  "city": "Oslo",
  "postCode": "0154",
  "country": "Norway"
  "countryCode": "NO",
  }

Adding a new required parameter​

A new required parameter that results in previously valid requests no longer being valid, is considered a breaking change.

Changing an endpoints URL​

It is considered a breaking change to change from POST:/accesstoken/get to POST:/accesstokens.

Adjusting the rate limit for an API​

Our API rate limits are set to a level that prevents obvious misuse, and the APIs respond with HTTP 429 Too Many Requests when the limits are exceeded.

We may adjust the rate limits when we see that APIs are used in an obviously incorrect way, and do not consider this a breaking change of the API itself.

Last updated on