Interfaces
Integration Guide
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:
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.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!​Last modified 1mo ago
Copy link