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
  • Requirements:
  • Recurring Payments with the Referenced Transactions Method
  • 1. Initial Transaction:
  • 2. Validating the transaction
  • 3. Recurring Transaction:
  • Recurring Payments using an alias
  • 1. Obtaining the Alias
  • 2. Recurring Transaction
  • Additional Information for Recurring payments
  • PSD2
  • Handling rejections
  • Automating the Recurring Payments

Was this helpful?

  1. Integration Guide
  2. Ways of integration
  3. Transaction Interface

Recurring Payments

PreviousTransaction InterfaceNextRefunds

Last updated 4 months ago

Was this helpful?

Before you start implementing Recurring Payments, please make sure, that you read and understood !

Recurring Payments are a feature sub-set of the and enable you -the merchant- to trigger subsequent transactions, without card holder presence.

Use-cases are subscription models, installments, "no-show" transactions for hotels and more.

It is important to understand, that each subsequent transaction is triggered by your system! Saferpay does not charge the customer, without you requesting it, which also applies to recurring payments.

Requirements:

  • a

  • a valid login access with a username and password for the .

  • one active Saferpay ecommerce terminal via which payment can be carried out and the associated

  • Saferpay terminal number (TerminalId parameter) and Saferpay customer number (CustomerId parameter).

  • valid acceptance agreement for credit cards or other payment methods, .

Supported Payment Methods

  • Apple Pay ()

  • American Express

  • Diners Club International & Discover

  • Google Pay ()

  • JCB

  • Mastercard

  • Postfinance Pay

  • SEPA Direct Debit

  • TWINT ()

  • Visa & V PAY

Recurring Payments with the Referenced Transactions Method

1. Initial Transaction:

This transaction basically captures the credit card details and sets a flag, to mark it as an initial transaction that can be used as a reference for recurring transactions.

{ 
"RequestHeader": {
   "SpecVersion": "[CURRENT SPEC-VERSION]",
   "CustomerId": "[your customer id]",
   "RequestId": "[unique request id]",
   "RetryIndicator": 0
 },
 "TerminalId": "[your terminal id]",
 "Payment": {
   "Amount": {
     "Value": "100",
     "CurrencyCode": "CHF"
   },
   "Recurring": {
     "Initial": true
   }
 },
 "Payer": {
   "LanguageCode": "en"
 },
 "ReturnUrls": {
   "Success": "[your shop payment success url]",
   "Fail": "[your shop payment fail url]"
 },
 "Styling": {
   "CssUrl": "[your shop css url]"
 }
}

2. Validating the transaction

Depending on the Interface used to initialize the transaction, you can validate the payment and assess transaction based information with either:

Both request will provide you with information about the Transaction including the 3D Secure response:

Here is an example of a PaymentPage Assert Response:

{
  "ResponseHeader": {
    "SpecVersion": "[CURRENT SPEC-VERSION]",
    "RequestId": "[your request id]"
  },
  "Transaction": {
    "Type": "PAYMENT",
    "Status": "AUTHORIZED",
    "Id": "MUOGAWA9pKr6rAv5dUKIbAjrCGYA",
    "Date": "2017-06-18T09:19:27.078Z",
    "Amount": {
      "Value": "100",
      "CurrencyCode": "CHF"
    },
    "AcquirerName": "AcquirerName",
    "AcquirerReference": "Reference"
  },
  "PaymentMeans": {
    "Brand": {
      "PaymentMethod": "SAFERPAYTEST",
      "Name": "SaferpayTestCard"
    },
    "DisplayText": "9123 45xx xxxx 1234",
    "Card": {
      "MaskedNumber": "912345xxxxxx1234",
      "ExpYear": 2021,
      "ExpMonth": 9,
      "HolderName": "Max Mustermann",
      "CountryCode": "CH"
    }
  },
  "Payer": {
    "IpAddress": "1.2.3.4",
    "IpLocation": "CH"
  },
  "ThreeDs": {
    "Authenticated": true,
    "LiabilityShift": true,
    "Xid": "ARkvCgk5Y1t/BDFFXkUPGX9DUgs=",
    "VerificationValue": "AAABBIIFmAAAAAAAAAAAAAAAAAA="
  }
}

You must save the Transaction.Id - value, returned in the PaymentPage Assert or Transaction Authorize response as this value will be used to reference recurring payments.

We recommend only to proceed, if the parameters Authenticated and LiabilityShift are true. This value indicates that the card holder has performed a full successful authentication (3D Secure process) at his bank. This option provides the highest level of security against fraud.

This initial transaction is saved for 5 years and can be used for the next step -the recurring transaction- within that time-frame.

IMPORTANT: This does not take the validity of the card itself into account! If the bank decides to e.g. block the card, the transaction will fail!

3. Recurring Transaction:

  1. Gather the TransactionId from the previous, initial, transaction

  2. Aquire the necessary payment-data e.g. Amount, Currency, OrderId etc.

    • You will get the authorization-response right away

  3. Validate the request response

  4. Depending on the outcome of step 4 you may

  5. Transaction is finished!

Here is an example of a Authorize Referenced Request:

{
  "RequestHeader": {
    "SpecVersion": "[CURRENT SPEC-VERSION]",
    "CustomerId": "[your customer id]",
    "RequestId": "[unique request id]",
    "RetryIndicator": 0
  },
  "TerminalId": "[your terminal id]",
  "Payment": {
    "Amount": {
      "Value": "100",
      "CurrencyCode": "CHF"
    },
    "Description": "Test123",
    "PayerNote": "Order123_Testshop"
  },
  "TransactionReference": {
    "TransactionId": "MUOGAWA9pKr6rAv5dUKIbAjrCGYA"
  }
}

The Amount is a mandatory value which can vary from the Amount of the initial transaction. A change of amount has to be communicated with the card holder and you must re-do this whole (Initial transaction and then reference to that transaction) process, to start the recurring-chain over again, otherwise, the bank may reject the recurring transaction.

Recurring Payments using an alias

1. Obtaining the Alias

Amount values that undercut a certain value, can cause problems during the 3D Secure-process, thus we recommend a value of 500 (5,00 €). As mentioned above, this transaction can be discarded. It is only, to prevend the mentioned issues with 3D Secure!

2. Recurring Transaction

  1. Gather the AliasId from the previous, initial, transaction

  2. Aquire the necessary payment-data e.g. Amount, Currency, OrderId etc.

    • You will get the authorization-response right away

  3. Validate the request response

  4. Depending on the outcome of step 4 you may

  5. Transaction is finished!

Requesting any exemption without the consent of your acquirer, can lead to rejections and your account being blocked!

Additional Information for Recurring payments

Recurring payments can be a bit more involved, than it seems on the surface. In order to ensure, that everything goes smooth, here are some tips for you, so everything is processed correctly.

PSD2

Handling rejections

Like any other transaction, a recurring payment can fail, e.g. due to a lack of funds on the side of your customer, the card expiring, or the card being stolen etc.

Handling these scenarios automatically can make things easier for you and your customers.

Depending on the type of the rejection, different actions need to be taken. You can implement a retry-mechanic, that re-attempts the transaction, after a certain amount (recommended are 24 hours) of time.

In these cases, we recommend informing your customer automatically via E-Mail, that maybe includes a link to your website, that allows the user to register his payment details for a new recurring-chain.

Automating the Recurring Payments

Automated recurring payments have to be triggered by the merchant's system. There are multiple ways to set up the automated triggering of payments. The easiest way is to set up a Cronjob (Linux) or a Task (Windows). With cronjobs, you can schedule a command or script on your server to run automatically at a specified time and date (e.g. every minute, every 15 Minutes, every hour, or every day at 10pm or even every Sunday.)

The cronjob can be linked with a script (e.g. PHP, or a Bash script) that will be executed, every time the cronjob is triggered to automatically perform transactions. You should decide when and how often the payments have to be triggered, depending on your business model and the prearranged scheduling of payments.

With this method, the initial transaction is performed with either the or with the leading the cardholder through a normal ecommerce payment process, including entering the CVC and 3DSecure authentication. The first transaction is flagged as initial transaction. The Transaction ID of the initial transaction can then be used for referenced/recurring transactions.

The Initial Transaction can be performed with the or via the , using Transaction Initialize and Transaction Authorize .

To define a transaction as the initial transaction, you need to set a special flag with either the or by defining the Container Payment.Recurring/Installment.

Here is an example of a with the Container Recurring:

Note, that the works just in the same way, as the Payment Page.

or

function.

The next step is to perform the actual recurring transaction(s). The API-Function that is required is . You have to simply submit the TransactionId from your initial transaction (discussed in step 2) to perform the recurring transaction(s).

Initialize and Execute Payment with

Each Transaction with the Status Authorized has to be to initiate the actual money transfer.

A second method is to use the Saferpay in conjunction with the with previously registered Aliases.

The alias can be obtained in multiple ways, . By using the , , or even a , with an it is possible to do an initial transaction, to validate the card (e.g. through 3D Secure), similar to the referenced transaction-process above!

Once the alias has been obtained, you can execute the subsequent transactions using . The alias has to be filled into the PaymentMeans.Alias container.

Initialize and Execute Payment with

Each Transaction with the Status Authorized has to be to initiate the actual money transfer.

Do not set the "Recurring"-exemption with the request, unless you know for sure, that you are allowed to do so!

As already mentioned above, is an extremely important bit of information for all merchants inside the European Economic Area. When handling recurring payments, please make sure, that you have read this chapter and implemented Saferpay accordingly., specifically in terms of Strong Consumer Authentication through .

However, there are cases, where the customer simply has to return to your shop, e.g. in case of a stolen card, or a , making it necessary to re-initialize the recurring process with new/updated payment means.

PaymentPage Interface
Transaction Interface
PaymentPage Interface
Transaction Interface
PaymentPage Initialize Request
Transaction Initialize Request
Transaction Interface
PaymentPage Assert
Transaction Authorize
Authorize Referenced
Transaction Authorize Referenced
Capture/Finalize the Transaction
Cancel/Abort the Transaction
captured
Secure Alias Store aka Secure Card Data
AuthorizeDirect Request
AuthorizeDirect Request
Transaction Authorize Direct
Capture/Finalize the Transaction
Cancel/Abort the Transaction
captured
Transaction Authorize Direct
PSD 2
3D Secure
More information about rejections and error handling in general, can be found over here.
the PSD2 chapter
Transaction Interface
Saferpay Business License
Saferpay Backoffice
that support recurring payments
using the Saferpay Secure Card Data store
Payment Page
Transaction Interface
Needs attention!
Needs attention!
Needs attention!
Standalone Registration
ONLINE_STRONG check
Soft Decline
PaymentPage Initialize Request
(click to enlarge)
(click to enlarge)