Management API
Automate your invoicing process with Saferpay
Documentation
Request Specification and technical documentation are available under https://saferpay.github.io/jsonapi/#ChapterRestApi.
Secure PayGate links
With the Saferpay Rest API, you can fully automate your invoicing process whether by e-mail, mail, or online. This not only saves you time, but also enables your customers to settle the invoice using their preferred payment method.
Requirements
The following requirements have to be met in order to use the Secure PayGate REST API:
You need a Saferpay Secure PayGate contract, in order to use the Secure PayGate in the first place
In conjunction with that, you need at least one Secure PayGate terminal, with attached payment methods of your choice.
A Saferpay eCommerce licence and thus the existence of a valid identification with a username and password for the Saferpay system, to access the necessary API functions.
Versioning
If you are implementing new payment methods and/or features, please make sure to implement the correct SpecVersion of our API.
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.45 specification, simply add the version to the URL like this:
Breaking changes
1.26+
The BillingAddressForm.Display parameter got removed.
Configuration
Before you can begin using the Secure PayGate, you need to configure it inside the Backoffice under Secure PayGate > Settings.
Creating a single-use link
A single-use link is meant to be paid once. Until it has been paid, it can be opened multiple times, unlike links, created by the payment API.
In order to create such a link, one must execute the SecurePayGate Create SingleUsePaymentLink request:
POST: /rest/customers/[customerId]/terminals/[terminalId]/spg-offers
Sending the Offer
An offer is not sent automatically!
It is intended for you to send the payment link using your own mail client, which is supported by a lot of environments and programming languages by default. This way, you have full control over the text and especially look and feel of your e-mail.
Query status of a single use link
If you want to know the status of a single-use link, you may use the SecurePayGate Get SingleUsePaymentLink request, using the OfferId returned within the SecurePayGate Create SingleUsePaymentLink response (see above):
GET: /rest/customers/[customerId]/terminals/[terminalId]/spg-offers/[offerId]
Inside the Backoffice
Payment links, that are created with the REST API, will also be displayed inside the Saferpay Backoffice.
The Application will be marked as RestApi.
The details of API-created links may be viewed, however they cannot be modified.
Connecting the JSON API
The Secure PayGate Management API can be connected with the Saferpay JSON API, specifically the Payment Page interface, enabling you to fully automate the creation, sending, and processing of your Secure PayGate offers. For that, you must define the {{{PAYMENTPAGETOKEN}}}, as described during the initial set-up, otherwise you do not have the necessary data to execute the next step.
Once the redirect and/or the notification call arrives at your web server, you can extract the {{{PAYMENTPAGETOKEN}}} and simply execute the Payment Page Assert. That will return the payment data of the Secure PayGate transaction to your system. This transaction is like a normal Payment Page transaction and further steps may be applied to it, for example the Capture, Partial Capture, or Cancel. Refunds via the API may also be executed if you wish.
Please note that the Secure PayGate settings also apply to these transactions, like the automatic Capture.
Try it!
We do offer a Demo Environment, where you can test the Secure PayGate Rest Api.
Secure Card Data
Similar to the Payment Page, the Secure PayGate API also has the ability to save a card during a transaction, using Secure Card Data. Simply add the RegisterAlias container to your request, as described in the request specification:
Example
At this moment, only the IdGenerator value RANDOM is supported!
To use said data, you have to use the Saferpay JSON API. Please refer to this chapter on how this can be done.
Delete an offer
It is possible to delete an already created offer using the Management API. However, for that, you must pay special attention as it may not be trivial at first glance.
The request-endpoint is the same as with the creation of the payment link. However, the HTTP-method is not. For deletion of the link, one must use HTTP-DELETE instead of HTTP-GET.
It is important to note, that DELETE only deletes the offer itself but does not kill the Payment session. If the customer already arrived on the payment page to pay the offer, SPG-delete will have no effect on the outcome of the payment.
It only prevents the payment link itself from being opened. If the link already has been opened, a payment can still be made. Though it will still void the payment link itself.
Here is an example from Mozilla about HTTP-DELETE.
Query information & account management
The Management API offers several methods to query account information and to manage said account. This enables you for instance to automatically configure your systems, should the need arise. It is also very helpful if you have multiple shops or franchises below you that all need a full list of payment methods and their configured currencies or information about available Saferpay functions in order to function properly. While this information can be gathered manually, the Management API offers a way to automatically configure everything, also eliminating the possibility for user-error.
The Licensing CustomerLicenseConfiguration request lets you queue information about available Saferpay functions, giving you an overview about everything that is available on this Saferpay account.
This is especially interesting for integrators that are offering their services to multiple merchants that want to use Saferpay, enabling their software to automatically set itself up.
Get Terminal configuration
The Management API offers a way to gather information about any terminal that is activated on the given Saferpay account.
There are two functions of interest:
This request will return a list of all activated terminals on a given CustomerId, containing their ID, type and descriptor. This is especially interesting for cases where the terminalId is not known and also offers a selection for the merchant if multiple terminals are activated.
Please mind the missing "s".
Once the terminalId is known, the Management API can be used to gather information about the terminal itself. The Terminal GetTerminal request will return the configuration of the terminal itself, like activated payment methods, available currencies for the given payment method, and also a URL to the currently used payment method logo, so you can easily stay up to date, even if the branding should change.
This request will return a list with all Payment Page configurations, that have been created on the account.
The Management API offers the possibility to create Access Tokens for the Saferpay Fields, enabling you to automatically set the fields up for the use in your webshop.
Fields Access Tokens can also be deleted via the same endpoint by executing an http DELETE request. Further information on this can be found in the API specification: Delete Access Token
The Management API also offers the ability to export information about all transactions that have been executed on a given Saferpay account.
However, there are certain rules that need to be followed when using this part of the API:
No parallel requests. If you have to use multiple requests to gather the information you need, execute them in serial, one after the other.
The maximum number of transactions that can be gathered with one request is limited to 2000.
Do not constantly ask for the same information/execute the exact same request. Only execute this report if necessary and save the returned data on your end.
Do not do lots of small queries, e.g. asking for every single transaction. This is meant for a bulk export. For single transactions, please make use of the other API functions first (e.g. Payment Page Assert and Transaction Authorize), if possible.
Please only gather transactions from the previous day onward. Take daily snapshots, if needed, to keep the amount of data that is transferred to a minimum.
Non compliance will lead to your account being blocked from using this API.
Technical aspects
The following technical aspects need to be met:
This function is only available for SpecVersion 1.48 and higher.
Note that this request is a GET request and not POST.
Request
We'll use the TransactionReporting GetTransactions request in order to get the transactions we want. The following example will give you a bit more understanding about the parameters that are specified within our API Specification:
This example will gather all SUCCESSFUL transactions from the account 123456 - this is your CustomerId - that were executed under the terminalId 17654321 that is connected to that account (Please use your terminalId.), between September 1st 12:49am and September 9th 2025 12:49am. It will start from the first page, aka the beginning of the transaction list, and it will return the first 1200 transactions that meet these criteria.
Please note that these filters do not need to be applied, as Saferpay has default values if they are left out; see our Specification for more info. This example just aims to explain all of them.
Exporting more than 2000 transactions
Should there be more than 2000 transactions within a given time frame, you must use paging in order to cycle through the chunks of data.
For instance, if you have made 10000 transactions within one day and you want to gather information on all of them, you first define your day with StartDate and EndDate. Depending on your processes, your business day may or may not go from 0:00am to 0:00am.
Then set a PageSize for your request. For the sake of this example, we will go with the maximum of 2000.
Execute the first request. Make sure to either not set PageNumber or set it to 1.
After the first request has been executed, you will get the TotalTransactions, which in this case is 10000. Divide the total number of transactions by your PageSize and round up to the next whole number. The result is the number of pages within your criteria. In this case, we will have 5 pages, each with 2000 transactions in them. Think of it as one dataset (of 10000 entries) that is divided into smaller, more manageable chunks (of 2000 entries), and PageNumber addresses these chunks directly.
So PageNumber 1 gathers all transactions from 10000-8001 - remember, we are taking from the top of the day, not the bottom -, PageNumber 2 returns 8000-6001, #3 will go from 6000-4001, and so on.
Repeat your request by iterating through the PageNumber until you have reached the previously calculated end of - in this example - 5.
Please always follow the mentioned rules above when executing multiple requests for large amounts of transactions.
Last updated
Was this helpful?