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 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. Furthermore, each Payment Method will list the minimum required SpecVersion under its requirements.

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.

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

Note: SpecVersion 1.1 and lower are not available, since those were only released for internal use.

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:

SpecVersion	Changes
1.36+	The values for the parameter Condition have been changed. WITH_LIABILITY_SHIFT is now 3DS_AUTHENTICATION_SUCCESSFUL_OR_ATTEMPTED IF_ALLOWED_BY_SCHEME is now NONE
1.33+	Error Behavior value ABORT has been renamed to DO_NOT_RETRY.
1.32+	The ReturnUrls.Success|Fail|Abort have been removed and replaced by a single ReturnUrl.Url. The outcome of the payment should be determined, by executing the next step, e.g. Transaction Authorize, or Payment Page Assert.
1.26+	The newely introduced parameter Billing|DeliveryAddressForm.AddressSource parameter now has a default Value of NONE. 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 Billing|DeliveryAddressForm.Display no longer exists and is replaced by AddressSource.
1.24+	The Notification.NotifyUrl has been replaced by SuccessNotifyUrl and FailNotifyUrl, to now also cover failed transactions, with the Payment Page. Both URLs behave like the old NotifyUrl, but now cover their respective cases, where the SuccessNotifyUrl is just the old NotifyUrl under a new name.
1.17+	Alias Insert Redirect: The RedirectUrl has been moved into the new Redirect container and out of the root-object.
1.12+	Notification E-Mail: Notification.MerchantEmail has been replaced with MerchantEmails, a string array, that now accepts up to 10 e-mails, instead of the one, with SpecVersion 1.11 and lower!
1.10+	Refund Handling: Due to the introduction of Partial Captures and thus the splitting of a transaction into multiple transactions, you must do a refund using the CaptureId provided in the Capture and MultipartCapture responses, instead of the TransactionId, as with SpecVersions 1.9 and lower!
1.9+	Shift of the ThreeDs-container: Due to the introduction of the Fraud Free Service, the Liability can now be accepted by one of two entities. Thusly the old ThreeDs container has been moved a level down, into the Liability container. This also applies for merchants, that do not use the Fraud Free Service!. For more information, please consult the API-Specification!

Tip: You should also keep an eye on our API Changelog, where we keep a record of API changes!