API versioning
When modifications are made to the API that are not compatible with previous versions, we release a new version through a custom http header where the value is the date of the new API release. This way you will not be exposed to backwards incompatible changes until you are ready to switch to a newer version. We keep the amount of backwards incompatible changes relatively small from version to version to allow for maintainable upgrades. To learn more about changes between our versions, please consult our Change logs.
Enforcement
With every API call, send the Rootline-Version header. Use the version you integrated against. The change logs below list every version, newest first. A version opens on its date at 00:00 UTC, and the API refuses it before that date. Fill out the version header key and value like shown here:
key: Rootline-Version
value: 2024-04-23
Failing to provide the Rootline-Version in your header, will lead to a 422 http error, and in the response body we will let you know that the error_code is missing_header where the missing field is Rootline-Version.
Webhook events will be sent according to the API version that you configured for your endpoints.
Change logs
2026-11-11
This version changes the capture, refund and cancel objects in webhook events. Up to version 2024-04-23 these objects send your own reference under the field named description. From this version on they have two fields:
reference: your own reference, as you sent it in the request.description: your description of the object. The field is absent when there is none.
A webhook endpoint that you create without api_version gets the latest version. From the release of this version on, that is 2026-11-11. Set api_version on the endpoint to keep an older version.
The Payment API itself is unchanged in this version.
2024-04-23
In this version we optimized the way payment network related parameters are collected. Going forward, a payment_rails object is used to collect all the details about the rails over which the payment is processed. These details include the customer's payment details, such as a bank account or card, as well as the payment method, such as ideal, and anything that is tightly related to it.
2024-02-17
We made three small, backwards incompatible changes in the Payment API for consistency.
shopper_canceled to customer_canceled
At Rootline we refer to a buying customer as customer. Therefore, we changed the 'shopper_canceled' scenario to show customer_canceled in the API. Specifically you will find this value in the response of the payment at authorizations.decline_details.code.
The authorization array is now called authorizations
In our first version we accidentally used a singular version for the authorization array. Now the array is correctly called authorizations.
The authentication array is now called authentications
In our first version we accidentally used a singular version for the authentication array. Now the array is correctly called authentications.
2023-07-19
This is our very first API version.