API Version Policy

At Placetopay we have only one version of the api available to date. So if you are going to connect or are already connected to our api, you are using the only version available.

As it is a single API version, all new features and adjustments are made in the same API version and are intended to be backward-compatible.

At Placetopay we consider the following changes backward compatible:

Add new resources and endpoints.

When a new functionality is added, it is very likely that it will be accompanied by a new endpoint and/or resource.

Example: If a new API was released to get users, the functionality would lead to a new User resource and a new api.com/users endpoint.

Add new optional parameters to existing API requests.

Due to the evolution of some functionalities, it is possible that we will add new optional parameters in the requests that can be made by integrator clients.

Example: In the CreateRequest api, an optional notificationUrl parameter could be added for those integrator clients who want to define the notification url of that session.

// CreateRequest body

{
  ...
  "payment": { ... }
  "notificationUrl": "http://example.com" // new optional parameter
  ...
}

This new parameter will be optional and will not affect existing integrations.

Add new properties to existing API responses

Due to the evolution of some functionalities, it is possible that some api responses include new properties.

Example: In the GetRequestInformation api the response can be modified to include a new cancelled property inside the subscription property

// GetRequestInformation Response
{
  ...
  "subscription": {
    ...
    "cancelled": true, // new property
    ...
  }
  ...
}

This new property will be included and will not affect existing integrations.

Change the order of properties in existing API responses.

Due to the evolution of some functionalities, it is probable that some api responses will change the order of their properties.

Example: In the GetRequestInformation api the response can be modified so that the order of the properties is different.

// current
{
  "requestId": "123",
  "status": { ... },
  ...
}

// changes to
{
  "status": { ... }, // changed order
  "requestId": "123",
  ...
}

This change will not affect existing integrations.

Change required parameters to optional in existing API requests.

Due to the evolution of some functionality, we may change an existing parameter that is required to optional in requests that can be made by integrator clients.

Example: In the CreateRequest api the required parameter ipAddress could be changed to be optional.

// CreateRequest body

{
  ...
  "payment": { ... }
  "ipAddress": "1.0.0.0.1" // changed to be optional
  ...
}

This change will not affect existing integrations.

The opposite cannot be done, that is, an optional parameter cannot be returned required.