LogoLogo
BlogLogin
English
English
  • An Introduction to Saferpay
    • Licensing
      • Legacy licensing
    • Reconciliation
    • Acquirers & Payment Methods
    • Web Shop Plugins and certified partners
      • ePages Beyond
      • ePages NOW
      • Magento 2
      • Odoo
      • PrestaShop
        • PrestaShop User Guide
      • Salesforce Commerce Cloud
      • SAP Commerce Cloud
      • Shopware 6
        • Shopware 6 User Guide - German
        • Shopware 6 User Guide - English
      • WordPress WooCommerce
      • Shopify
    • Supported Languages
    • Common Saferpay terms - Glossary
  • News
    • Changes for transactions without customer presence
    • Changes for the Saferpay Hosted Forms, Fields and Payment Page
  • Quick Links
    • Web Shop Plugins and certified partners
    • Secure PayGate
    • User Administration
    • Payment Page Configuration
    • Risk Management
    • API Authentication
  • Interfaces
    • Payment API (aka JSON API)
    • Management API
    • Backoffice
      • The Home screen
      • Batch Processing
      • Transactions
        • Transaction Details
        • Batch Close
        • Declined transactions
        • Pending authorizations
        • Analytics
        • SEPA Refunds Export
        • Authorization & Payment
        • Credit
      • Risk Management
      • Secure PayGate / Payment Links
      • Secure Card Data
        • Secure Card Data Details
      • Settings
        • JSON API basic/Client Certificate authentication
        • User Administration
        • Payment Page Configuration
      • Online Support
      • User Profile
    • Saferpay OnSite
    • Feedback
  • Integration Guide
    • Integrating Saferpay
    • Ways of integration
      • General Information
        • Data Security and PCI DSS
        • Versioning
        • 3-D Secure
        • PSD2
        • Dynamic Currency Conversion
        • Iframe Integration and CSS
        • Fraud Intelligence
          • Silver
          • Fraud Intelligence Integration
      • Payment Page
        • Payment Page checklist
      • Transaction Interface
        • Recurring Payments
        • Refunds
          • SEPA Refunds
      • Capture and Daily Closing
        • Partial Captures
          • Marketplace
      • Secure Card Data - Tokenization
      • Saferpay Fields
      • Inquire Interfaces
      • Mobile Integration
      • Omni-Channel
      • Mail Phone Order
      • Error Handling
      • API Health Check
      • Saferpay API Specification
    • Payment Methods & Wallets
      • General and special cases
      • Account-to-Account Payments
      • Alipay+
      • Apple Pay
      • American Express
      • Bancontact
      • Billie
      • blik
      • Click to Pay
      • Diners Club International & Discover Card
      • eps
      • giropay
      • Google Pay
      • iDEAL 2.0
      • JCB
      • Klarna Payments
      • Maestro International
      • Mastercard
      • paydirekt
      • PayPal
      • PostFinance Pay
      • Przelewy24
      • Reka
      • SEPA Direct Debit
      • Sofort by Klarna
      • TWINT
      • UnionPay
      • Visa & V PAY
      • WeChat Pay
      • WL Crypto Payments
    • Testing
    • Go-Live
    • Frequently Asked Questions
    • Saferpay Demo
      • Saferpay Demo Environment
      • Saferpay Demo Shop
    • Support
    • Changelog
Powered by GitBook
On this page
  • Documentation
  • Secure PayGate links
  • Requirements
  • Versioning
  • Configuration
  • Creating a single-use link
  • Sending the Offer
  • Queue status of a single use link
  • Inside the Backoffice
  • Connecting the JSON API
  • Try it!
  • Secure Card Data
  • Delete an offer
  • Queue information & account management
  • Customer License Configuration
  • Get Terminal configuration
  • Create Access Token
  • Delete Access Token

Was this helpful?

  1. Interfaces

Management API

Automate your invoicing process with Saferpay

PreviousPayment API (aka JSON API)NextBackoffice

Last updated 3 months ago

Was this helpful?

Documentation

Request Specification and technical documentation is available under

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.4 specification, simply add the version to the url like this:

https://saferpay.github.io/jsonapi/1.14/

Breaking changes

SpecVersion
Changes

1.26+

The BillingAddressForm.Display parameter got removed.

Configuration

Creating a single-use link

A single-use link is meant to be payed once. Until it has been payed, it can be opened multiple-times, unlike links, created by the payment API.

POST: /rest/customers/[customerId]/terminals/[terminalId]/spg-offers

{
  "Payment": {
    "Amount": {
      "Value": "404",
      "CurrencyCode": "CHF"
    },
    "OrderId": "094c2a7ce1374f7ca184591f123b154d",
    "Options": {
      "PreAuth": true
    }
  },
  "ExpirationDate": "2020-04-23",
  "Payer": {
    "LanguageCode": "de",
    "BillingAddress": {
      "FirstName": "John",
      "LastName": "Doe",
      "Company": "Worldline",
      "Gender": "MALE",
      "Street": "Mustergasse 123",
      "Zip": "8008",
      "City": "Zurich",
      "CountryCode": "CH",
      "Email": "payer@provider.com"
    }
  }
}
{
  "OfferId": "503a3d7b-072b-400f-9e7e-8ec15191c737",
  "PaymentLink": "https://www.saferpay.com/SecurePayGate/Payment/123456/12345678/503a3d7b-072b-400f-9e7e-8ec15191c737"
}

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.

Queue status of a single use link

GET: /rest/customers/[customerId]/terminals/[terminalId]/spg-offers/[offerId]

No payload needed
{
  "OfferId":"503a3d7b-072b-400f-9e7e-8ec15191c737",
  "PaymentLink":"https://www.saferpay.com/SecurePayGate/Payment/123456/12345678/503a3d7b-072b-400f-9e7e-8ec15191c737"
  "Status":"OPEN",
  "Payment":{
    "Amount":{
      "Value":"100",
      "CurrencyCode":"CHF",
    },
    "OrderId":"cd0005bf21bb4906bcbea939d74cee72",
    "Description":"Hallo"
  },
  "CreationDate":"2023-03-01T11:37:47.682+01:00",
  "ExpirationDate":"2023-04-01T00:00:00.000+02:00"
}

Inside the Backoffice

The Application will be marked as RestApi.

The details of API-created links may be viewed, however it cannot be modified.

Connecting the JSON API

Try it!

Secure Card Data

Similar to the Payment Page, the Secure PayGate API also has the ability to save a card, during a transaction. Simply add the RegisterAlias container to your request, as described in the request specification:

Example

{
  "Payment": {
    "Amount": {
      "Value": "404",
      "CurrencyCode": "CHF"
    },
    "OrderId": "094c2a7ce1374f7ca184591f123b154d",
    "Options": {
      "PreAuth": true
    }
  },
  "ExpirationDate": "2020-04-23",
  "Payer": {
    "LanguageCode": "de",
    "BillingAddress": {
      "FirstName": "John",
      "LastName": "Doe",
      "Company": "Worldline",
      "Gender": "MALE",
      "Street": "Mustergasse 123",
      "Zip": "8008",
      "City": "Zurich",
      "CountryCode": "CH",
      "Email": "payer@provider.com"
    }
  },
  "BillingAddressForm": {
    "Display": true
  },
  "RegisterAlias": {
    "IdGenerator": "RANDOM"
  }
}

At this moment, only the IdGenerator value RANDOM is supported!

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.

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.

Queue information & account management

The Management API offers several methods to queue 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.

Customer License Configuration

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:

Please mind the missing "s".

Create Access Token

Delete Access Token

Before you can begin using the Secure PayGate, you need to configure it inside the Backoffice under .

In order to create such a link, one must execute the :

If you want to know the status of a single-use link, you may use the , using the OfferId returned within the SecurePayGate Create SingleUsePaymentLink response (see above):

Payment links, that are created with the REST Api, will also be displayed inside the

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}}}, , otherwise you do not have the necessary data to execute the next step.

Once the redirect and/or the notification call arrives at your webserver, you can extract the {{{PAYMENTPAGETOKEN}}} and simply execute the . That will return the payment data of the Secure PayGate transaction to your system. This transaction is like a normal transaction and further steps may be applied to it, for example the , , or . may also be executed, if you wish.

As of now the automatic capturing-option, as described in the , does not apply to transactions, made via the Secure PayGate API! You always either have to capture them manually through the Saferpay Backoffice, or via the JSON API, as described above!

We do offer a Demo Environment, where you can .

Similar to the Payment Page, the also has the ability to save a card, during a transaction, using . Simply add the RegisterAlias container to your request, as described in the request specification:

To use said data, you have to use the Saferpay JSON API. Please , on how this can be done.

The is the same, as with of the payment link. However the HTTP-method is not. For deletion of the link, one must use HTTP-DELETE, instead of HTTP-GET.

Here is an

The lets you queue information about available , giving you an overview about everything, that is available on this Saferpay account.

This request will return a list of all activated terminals on a given , containing their , type and descriptor. This is especially interesting for cases, where the terminalId is not known and also offer a selection for the merchant, if multiple terminals are activated.

Once the terminalId is known, the Management API can be used to gather information about the terminal itself. The 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.

The Management Api offers the possibility, to for the , 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. Further information on this can be found in the API specification:

SecurePayGate Create SingleUsePaymentLink request
SecurePayGate Get SingleUsePaymentLink request
Payment Page Assert
Payment Page
Capture
Partial Capture
Cancel
Refunds via the API
test the Secure PayGate Rest Api
Secure PayGate API
Secure Card Data
example from Mozilla about HTTP-DELETE.
Licensing CustomerLicenseConfiguration request
Saferpay functions
Terminals GetTerminals
Terminal GetTerminal
Terminal GetTerminal request
create Access Tokens
Saferpay Fields
Delete Access Token
request-endpoint
the creation
https://saferpay.github.io/jsonapi/#ChapterRestApi.
Secure PayGate > Settings
Saferpay Backoffice.
as described during the initial set-up
Secure PayGate manual
CustomerId
ID
refer to this chapter
Technical Flow
(click to enlarge)
(click to enlarge)