# Versioning

If you are implementing new payment methods and/or features, please make sure to implement the correct **SpecVersion** of our API. If you are unsure, you should refer to the newest SpecVersion. [Our Changelog](https://saferpay.github.io/jsonapi/Changelog.html) will give you further information about the current and past spec-versions. You'll also find the newest Version in the top left of our [API Specification](https://saferpay.github.io/jsonapi/). Furthermore, each Payment Method will list the minimum required SpecVersion under its requirements.

{% hint style="warning" %}
**Attention:** This guide will always assume the latest SpecVersion of the Saferpay JSON API, unless stated otherwise. While some features do work with older versions, please always consult the specification and, if need be, the version, you have currently implemented, as stated below.
{% endhint %}

Furthermore, it is possible to go back to previous spec-versions, by adding the version to the url. For example, if you want to go back to the 1.4 specification, simply add the version to the url like this:

> <https://saferpay.github.io/jsonapi/1.4>

{% hint style="info" %}
&#x20;**Note:** SpecVersion 1.1 and lower are not available, since those were only released for internal use.
{% endhint %}

## Important Changes in certain SpecVersions

If you plan on upgrading to a newer SpecVersion, you may have to keep the following major and breaking changes in mind:

<table data-header-hidden><thead><tr><th width="155">SpecVersion</th><th>Changes</th></tr></thead><tbody><tr><td><strong>SpecVersion</strong></td><td><strong>Changes</strong></td></tr><tr><td><strong>1.40+</strong></td><td><ul><li>Removed every instance of the values for <strong><code>POSTFINANCE</code></strong> and <strong><code>POSTCARD</code></strong> inside the API, as it has been replaced by <a href="/pages/ZFuM3ctYf89nJscRdzqe">Postfinance Pay</a>.</li><li>The <strong>Transaction/RedirectPayment</strong> function has been deprecated and no longer works.</li></ul></td></tr><tr><td><strong>1.39+</strong></td><td>The <strong><code>Styling</code></strong> container has been removed from the <a href="/pages/-Me4jFEJClrxX7AII0gz">Payment Page Interface</a>. <strong>The Payment Page does no longer support CSS styling!</strong></td></tr><tr><td><strong>1.36+</strong></td><td><p>The values for the parameter Condition have been changed.</p><ul><li><strong><code>WITH_LIABILITY_SHIFT</code></strong> is now <strong><code>3DS_AUTHENTICATION_SUCCESSFUL_OR_ATTEMPTED</code></strong></li><li><strong><code>IF_ALLOWED_BY_SCHEME</code></strong> is now <strong><code>NONE</code></strong></li></ul></td></tr><tr><td><strong>1.33+</strong></td><td>Error <strong><code>Behavior</code></strong> value <strong><code>ABORT</code></strong> has been renamed to <strong><code>DO_NOT_RETRY</code></strong>.</td></tr><tr><td><strong>1.32+</strong></td><td>The <strong><code>ReturnUrls.Success|Fail|Abort</code></strong> have been removed and replaced by a single <strong><code>ReturnUrl.Url</code></strong>.<br>The outcome of the payment should be determined, by executing the next step, e.g. <a href="/pages/-Me5IpUwX8LC1JQp3T5J#id-4-transaction-authorize">Transaction Authorize</a>, or <a href="/pages/-Me4jFEJClrxX7AII0gz#id-4-paymentpage-assert">Payment Page Assert</a>.</td></tr><tr><td><strong>1.26+</strong></td><td>The newely introduced parameter <strong><code>Billing|DeliveryAddressForm.AddressSource</code></strong> parameter now has a default Value of <strong><code>NONE</code></strong>. This means, that, per default, no address will be gathered, be it through Saferpay, or the payment method! You must keep this in mind, if you gather your customers address through Saferpay, or the payment method (e.g. PayPal). Likewise the parameter <strong><code>Billing|DeliveryAddressForm.Display</code></strong> no longer exists and is replaced by <strong><code>AddressSource</code></strong>.</td></tr><tr><td><strong>1.24+</strong></td><td>The <strong><code>Notification.NotifyUrl</code></strong> has been replaced by <strong><code>SuccessNotifyUrl</code></strong> and <strong><code>FailNotifyUrl</code></strong>, to now also cover failed transactions, with the<a href="/pages/-Me4jFEJClrxX7AII0gz#1-paymentpage-initialize-request"> Payment Page</a>. Both URLs behave like the old <strong><code>NotifyUrl</code></strong>, but now cover their respective cases, where the <strong><code>SuccessNotifyUrl</code></strong> is just the old <strong><code>NotifyUrl</code></strong> under a new name.</td></tr><tr><td><strong>1.17+</strong></td><td><strong>Alias Insert Redirect:</strong> The <strong><code>RedirectUrl</code></strong> has been moved into the new <strong><code>Redirect</code></strong> container and out of the root-object.</td></tr><tr><td><strong>1.12+</strong></td><td><strong>Notification E-Mail: <code>Notification.MerchantEmail</code></strong> has been replaced with <strong><code>MerchantEmails</code></strong>, a string array, that now accepts up to 10 e-mails, instead of the one, with SpecVersion 1.11 and lower!</td></tr><tr><td><strong>1.10+</strong></td><td><strong>Refund Handling:</strong> Due to the introduction of <a href="https://saferpay.github.io/sndbx/marketplace.html">Partial Captures</a> and thus the splitting of a transaction into multiple transactions, you must do a refund using the <strong><code>CaptureId</code></strong> provided in the <a href="https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_Capture">Capture</a> and <a href="https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_MultipartCapture">MultipartCapture</a> responses, instead of the <strong><code>TransactionId</code></strong>, as with SpecVersions 1.9 and lower!</td></tr><tr><td><strong>1.9+</strong></td><td><strong>Shift of the ThreeDs-container:</strong> Due to the introduction of the Fraud Free Service, the Liability can now be accepted by one of two entities. Thusly the old <strong><code>ThreeDs</code></strong> container has been moved a level down, into the <strong><code>Liability</code></strong> container. <strong>This also applies for merchants, that do not use the Fraud Free Service!</strong>. For more information, please consult the <a href="https://saferpay.github.io/jsonapi">API-Specification!</a></td></tr></tbody></table>

{% hint style="warning" %}
**This list does not include all changes**, that have been made to Saferpay. These are just the changes, that will most likely impact your development.

An extensive list of all changes, can be found in our Changelog (see below).
{% endhint %}

{% hint style="info" %}
**Tip:** You should also keep an eye on [our API Changelog](https://saferpay.github.io/jsonapi/#changelog), where we keep a record of API changes!
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.saferpay.com/home/integration-guide/general-information/versioning.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.