Interfaces
Integration Guide
Magento 2 User Guide
Saferpay Plugin for Magento 2
ABOUT DOCUMENT
Version No.
Prepared by
Version Changes
Date
V1.0.0
Deepthi Joseph & Shanty Justus
Prepared initial document version
31.03.2020
V1.0.1
Soumia George,
Added Amasty Recurring Payment module and limitations with the Recurring module
09.04.2020
V1.0.2
Shanty Justus
PSD2 Changes
06.05.2020
V1.0.3
Erich Zeiler-Rausch
Proofread and public release
14.05.2020
V1.0.4
Deepthi Joseph & Shanty Justus
iDEAL Preselection for bank account, Saferpay Field for "Save card", Redirect URL in lightbox for checkout with Saferpay Fields and Transaction Interface
06.10.2020
V1.0.5
Shanty Justus, Deepthi Joseph
Compatible with Magento version 2.4.1 and Amasty Subscriptions & Recurring Payments Version 1.6.3, Added Klarna payment method.
23.12.2020
V1.0.6
Shanty Justus
Compatible with Magento version 2.4.2, Fixed the compatibility issues when Amasty Subscriptions & Recurring Payments extension is not installed, Fixed the error of sending incorrect LanguageCode to API
23.04.2021
V1.0.7
Shanty Justus
Compatible with Magento version 2.3.7 and 2.4.2 p1
10.06.2021
V1.0.8
Shanty Justus
Deepthi Joseph
Crypto Payments, New countries for Klarna Payments, New currencies for SOFORT, EPS Refund support, Removed Bonus card
14.07.2021
V1.0.9
Shanty Justus
Deepthi Joseph
Compatible with Magento version 2.4.3, 2.3.7-p2 and 2.4.3-p1 and Amasty Subscriptions & Recurring Payments Version 1.6.8
API Spec version updates from 1.23 to 1.25
14.12.2021
ABOUT MAGENTO MODULE
This module is implemented to integrate Saferpay Payment methods in Magento. It supports the following payment methods of Saferpay to work with default Magento 2 checkout.
1] VISA
2] MASTERCARD
3] MAESTRO
4] AMERICAN EXPRESS
5] BANCONTACT
6] DINERS/DISCOVER
7] JCB
8] SEPA ELV
9] MYONE
10] MASTERPASS
11] UNIONPAY
12] PAYPAL
13] TWINT
14] PAYDIREKT
15] IDEAL
16] EPRZELEWY
17] POSTFINANCE CARD
18] POSTFINANCE EFINANCE
19] APPLE PAY
20] ALIPAY
21] CREDITCARD (SAFERPAY FIELDS)
22] SOFORT
23] GIROPAY
24] EPS
25] BILLPAY PURCHASE ON RECEIPT
26] BILLPAY DIRECT DEBIT
27] KLARNA PAYMENTS
28] WL CRYPTO PAYMENTS
This module supports all the features of online payment methods like invoice capturing, refunding & cancellation. All these payment operations done in the Magento backend will be synced to Saferpay account also.
REQUIRMENTS
To install and configure Saferpay module in Magento, the following is required:
· Magento installation with version between 2.0.2 to 2.4.3-p1
· The license for the Saferpay module.
· A valid Saferpay account with at least one active Saferpay terminal through which payments can be carried out
· API credentials like Terminal ID, Customer ID, JSON Username and JSON Password for the Saferpay Live- and/or Test environment
· Valid acceptance agreement for payment methods.
INSTALLATION
To install Saferpay module follow the steps below.
Step 1: Download Saferpay module extension and unzip it.
Step 2: Access your web server directories and upload the content of the folder into the root directory
Step 3: Run the following commands to complete the installation.
1. Enable the module
php bin/magento module:enable --clear-static-content Saferpay_PaymentService
php bin/magento module:enable --clear-static-content Saferpay_RecurringPayments ( Disable this module if the shop does not use Amasty recurring module)
2. Update of the database
php bin/magento setup:upgrade
3. Generate and pre-compile classes
php bin/magento setup:di:compile
4. Deploy static files
php bin/magento setup:static-content:deploy [locale]
[locale] should be replaced by ISO-639 language codes for which to output static view files.
CONFIGURATION
Saferpay module configuration includes two section
1. General configuration
2. Payment method specific configuration
GENERAL CONFIGURATION
Configure general module settings from Stores > Configuration > Sales > Saferpay Tab
The following configuration options are available in General section
1. Environment: It defines the Saferpay Operation mode. The dropdown will allow merchant to quickly switch between live and test environment. By default, test mode is selected
2. Test Customer ID/Live Customer ID
3. Test Terminal ID
4. Test JSON Username
5. Test JSON API Password
6. Generate Saferpay Ffields access token and URL automatically
By enabling this, you can automatically create Access Tokens and API URL for the Saferpay Fields.
Note: Configuration fields from 1 to 5 must be filled in if you want to create access token automatically.
7. Enter Shop URL - for which access tokens to be generated
8. Test Saferpay Fields API Key
9. Test Saferpay Fields API URL
8., 9.: the details can be obtained from Saferpay Backend -> Settings -> Saferpay Fields Access Tokens
10. Test Hosted Field JS URL
This is the Saferpay Fields Javascript library URL. Do not edit this if you are unaware of the functionality
11. Test Base URL
These fields already have default values of API base URL. Do not edit this if you are unaware of the functionality
Fields from 2 to 9 may vary based on the operation mode opted. Data is available from Saferpay Backoffice. To get access information for live environment you have to request an offer here. To get access information to test account please follow this link.
To get JSON API username and password you have to login to Saferpay management interface and go to Settings -> JSON API basic authentication. Please refer https://www.six-payment-services.com/en/site/e-commerce-developer/integration.html for more information
12. Licence: Choose the Saferpay licence you own.
Saferpay has two licenses:
- Saferpay eCommerce
- Saferpay Business
In case you are using Saferpay Business without the corresponding license, the API will throw an error.
13. Liability Shift Behaviour
This field determines how to handle the transactions when Liability Check for card Fails. When using this functionality, the liability shifts to the authorizing bank and the store owner receives no claim for any chargeback if a fraudulent card is used on their website.
It has two options:
- Manual Capture: Transactions with false LiabilityShift are not captured, but it gets authorized. Later the merchant can capture, or cancel the order as he wish.
- Autocancel: Transactions with false LiabilityShift are cancelled automatically
14. Check extra level of Authentication
Recommended for high risk businesses (Jewellery, Electronics, etc.) to stick to the highest level of security.
15. Recurring SCA challenge for PSD2 Compliance
Saferpay module is compatible with Amasty recurring module. This field is applicable only for orders with subscription products. It ensures the PSD2 compliance of the recurring payments done through Saferpay while Amasty extension is enabled.
16. Recurring Customer Authentication Email Template
There is a possibility for payment failure due to soft decline of cards during recurring transaction. During such scenarios this template is used to send email to customers notifying them about transaction error.
17. Re-enter CVC value when using saved cards for payment
This option is used to provide additional security when the customer uses saved cards for the checkout. While this option is enabled, it asks the cardholder to re-enter his CVC if he uses saved card for checkout, and hence the transaction would be fully secure and PCI compliant
18. Merchant email
Email addresses (Merchant email) to which a confirmation email need to be send after successful payment authorizations. (Applicable only for payment page authorization)
19. Order Description
A human readable description provided by the merchant that will be displayed in Payment Page.
20. CSS URL
Enter a valid CSS URL which is included in the payment page. This file must be hosted on an SSL/TLS secured web server (the URL must start with https://) Example: https://merchanthost/merchant.css.
21. Payment Page Theme
Choose the theme to customize the appearance of Saferpay payment pages. Per default a lightweight responsive styling will be applied.
22. Saferpay Configuration
Saferpay Payment Page configurations is used to configure design and other details inside hosted pages. The configuration can be created from Saferpay Backoffice ('Settings > PaymentPage Configuration'). The configuration marked as 'default' will be used as the standard setting if none
23. Enable Log
All the error details regarding a transaction will be logged to custom log if this option is enabled. Refer Log section for more information
24. Email Template on cancellation of order
There may be possibilities for cancelling authorized transaction due to failed 3Ds check. During such scenarios this template is used to send email to customers notifying them about payment cancellation.
PAYMENT METHOD SPECIFICS
Masterpass - Refer Masterpass is a Wallet-Solution introduced by Mastercard. Please refer https://saferpay.github.io/sndbx/Masterpass.html
SOFORT - SOFORT is a third party means of payment by Klarna Group. Refer https://saferpay.github.io/sndbx/sofort.html
Klarna Payments - Klarna Payments is a 3rd party payment method, that is split into three ways of payment: Pay Now, Pay Later and Slice It/Financing. Refer https://saferpay.github.io/sndbx/KlarnaPayments.html
PAYMENT METHOD SPECIFIC CONFIGURATION
Individual payment methods which come under Saferpay can be configured from System > Configuration > Sales > Payment Methods section. Not all payment will be in your contract so be careful while enabling payment methods.
Saferpay specific configuration are explained in detail.
1. Enabled
Enable or Disable payment methods
2. Title
The title displayed to the customer on the store front during checkout.
3. Description
Description for the payment
4. Payment from Applicable Countries
By default, it is set to All Allowed Countries.
5. Payment from Specific Countries
If you wish to accept payment from specific countries, you can select the countries in Payment from Specific Countries.
6. Accepted Currencies
Choose the currencies that can be processed with this payment. If no currency is selected payment will not be available even though it is enabled individually.
Some payments like Klarna or WL Crypto Payments may have country and currency restrictions. So be careful in choosing countries and ensure that these countries are activated in your Klarna payment settings in Saferpay account also.
For Klarna to work properly, currency code should be in-line with country code Refer https://developers.klarna.com/documentation/klarna-payments/in-depth-knowledge/puchase-countries-currencies-locales/
Saferpay settings for Klarna
7. Use Base Currency
Defines whether Magento base currency should be used for processing the transaction. If this is enabled, only the payment methods that supports base currency will be listed during checkout.
8. Authorisation Method
Authorisation Method defines how the payment method is displayed and processed. Some payments support multiple authorisation methods while others support single.
- Payment page – During the order processing the user is redirected from the Magento shop to the Saferpay payment gateway to process the payment. On successful completion of the payment the user will be redirected back to the Magento shop. The Saferpay Payment Page Interface is intended for a simplified and universal integration of the payment process by using the PaymentPage payment form. The Saferpay Payment Page can be used both with a Saferpay eCommerce license and with a Saferpay business license. All Saferpay supported payment methods can be processes with the Payment Page Interface.
- Transaction Interface - During the order processing the user is served with Saferpay payment forms opened in a lightbox within the Magento shop. The Transaction Interface is an extension to Payment Page Interface. It offers the Hosted Entry Form (HEF) to process card payments seamlessly. This interface can also be used in combination with Secure Card Data to store/tokenize payment data during the payment process. The Transaction Interface is only for holders of a business licence on the live system.
- Saferpay Fields - Saferpay fields will be hosted on Saferpay-side and will offer you a level of flexibility and the possibilities, similar to using your own form. The data is captured by a fully PCI-certified system.
9. Capture Type
This indicated how payment provider should behave when order is created. There are two options:
- Autocapture: It will automatically capture the amount in the order.
- Manual capture: The payment will be authorized, but merchant will have to capture manually form shop Backend
10. Invoice Generation
This field determines when to generate invoice for the payments made through Saferpay if the capture type is set to Manual.
For automatic Captures invoice will be generated instantly after payment in paid state.
- Manual: Invoice should be generated manually by merchant from Magento Backend.
- Automatic: Invoice will be generated automatically upon payment authorize in pending state.
11. Send Invoice Email
If “send invoice” is enabled, invoice email is sent automatically after invoice capture.
12. Pre-Authorize Transaction
When set to true the transaction is processed as pre-authorization otherwise as final authorization. If pre-authorisation is selected, the capture of the payment is prevented even though the capture type is “Autocapture “.
13. Show Payment Icon
When enabled, the payment brand icon will be shown in checkout page and order email.
14. Display Payment ID
This field determines whether transaction Id of the payment should be displayed in order confirmation page and order email.
15. Send Customer Address
This option will send customer address to Saferpay.
16. Display card holder name on Saferpay
This parameter let you customize the holder name field on the card entry form. Per default, a mandatory holder name field is shown.
17. Register alias and use during checkout
By enabling this, the customer can register cards and use it for future payments. Card details will be stored in Saferpay. This option is available only for Transaction Interface Authorisation method.
18. Send Customer confirmation email from Saferpay
Confirmation email will be sent to the customer after successful authorizations from Saferpay (Applicable only for payment page authorization)
19. Minimum Order Total
Using this field merchant can set a minimum order limit. If the grand total of the order is less than the Minimum Order Total value, the payment cannot be processed through the payment method.
20. Maximum Order Total
You can specify the maximum amount for the transaction that can be processed through this payment method.
21. Sort Order
This option is for sorting the payment methods to display in the checkout page.
Once you have configured Saferpay payment method, review all the settings carefully. If everything is fine, click Save Config button at the top right corner.
22. Payment Brands
This configuration is available only for Credit Card and Apple Pay payments. It enables the merchant to choose the payment brands which will be accepted by these payments. By default, all brands are selected.
The selected brands will be accepted only if it supports the currency opted for Saferpay transactions.
Payment Brands
23. Saferpay Fields CSS URL
Configuration specific to Credit Card payment. It defines the url to an external CSS, to be applied to Saferpay Fields if the merchant wants to customize the existing design.
Saferpay Fields CSS URK
24. Pre-Select issuer bank account
iDEAL Payment allows the customers to pre-select the issuer bank from Magento itself. The customer will be redirected directly to the selected bank and thus skipping the bank selection page during payment process.
iDEAL bank pre-selection
Attention: These Values are issued by iDeal, please check https://docs.saferpay.com/home/integration-guide/payment-methods/ideal. We have added option to add more bank when Saferpay support more banks in future.
We have provided an interface to edit/add the bank name and issuer Id if needed. You can configure it from the section Admin Panel > Stores > Configuration > Sales > Saferpay >iDeal Bank Configuration section
Once you have configured Saferpay payment method, review all the settings carefully. If everything is fine, click Save Config button at the top right corner.
This preselect feature can be enable/disable from iDeal backend configuration.
SAFERPAY FEATURES
DESIGN CUSTOMIZATION
If you want to customize the default design of Saferpay interface, Saferpay provides the following options
1. CSS-Styling
The CSS styling-options can be used over following methods.
- Payment page
- Transaction Interface
- Alias Insert
Note: The CSS file that is referenced by the CssUrl parameter must be stored on a web server that supports HTTPS.
Refer https://docs.saferpay.com/home/integration-guide/iframe-integration-and-css#using-css for detailed information
2. Theme
This parameter let you customize the appearance of the displayed payment pages. Per default a lightweight responsive styling will be applied. If you don't want any styling use 'NONE'.
3. Payment Page Configuration
You can create different PP configurations to be applied over Transaction initialize and PaymentPage Initialize. The configuration itself can be created inside the Saferpay Backend under “Settings > Payment Page Configuration”.
Note: If a custom CSS is provided, any design related settings set in the payment page config (PPConfig) will be ignored and the default design will be used.
ORDER MANAGEMENT
CAPTURE PAYMENT
If in the payment configuration “Capture type” is set to “Automatic”, merchant don’t need to do anything from Magento backend. Payments will be captured automatically by the system and no adjustments is possible for created invoice.
When the “Capture type” is set to “Manual”, merchant will have to capture payments manually through backend.
In order to create invoice, follow these steps
1. Open the order you want to create invoice
2. Click on the invoice option in header of the sales order
3. Ensure that Capture Online is selected at the bottom of the Invoice
4. Click Submit Invoice. If successful, an invoice will be created.
If the Capture type is set to Manual and Invoice generation to Automatic, then invoice will be created in pending state. All you need to do is to capture that invoice.
MULTIPART CAPTURE
Saferpay offers the option to do Partial Captures on transactions made with only certain payment methods. Magento supports multiple invoices for an order and each invoice can be captured separately. Please note that Magneto doesn’t support multiple capture of a single invoice.
Multipart capture can be used over following methods
- Visa
- Mastercard
- Maestro
- PayPal
CANCEL PAYMENT
Only authorized, but not captured orders can be cancelled. Cancellation of an order prevents any future change from being made to it.
In order to cancel an order, click on the Cancel option in header of the sales order.
VOID PAYMENT
Authorized transaction can be cancelled by issuing a void in Magento. It will initiate money flow to the card holder by cancelling the transaction and prevent any further online transaction process for that order.
Note: Captured transaction cannot be cancelled but can be refunded.
To Void payment, follow the below steps
1. Go to Sales -> Orders and open the order you want to cancellation
2. Click on the Void option in header of the sales order and confirm the Void
3. Confirm the transaction and if successful it gets cancelled
REFUND PAYMENT
Captured transactions can be refunded. Multiple refunds are possible on each invoice.
In order to refund payment, follow these steps
1. Open the order and navigate to invoice section
2. Select the invoice that you would like to refund and enter the invoice page by clicking View
3. Click on Credit Memo option in the invoice page
4. Adjust the item to refund by editing “Items to refunds” section
5. Edit the Refund Totals Section to adjust the amount to refund. It is not possible to refund more than the total order amount.
6. Click the Refund button at the bottom of the page.
7. If successful, credit memo will be issued.
Note: Online credits can only be issued only from the invoice page in Magento, and not from the Order page.
TRANSACTION OVERVIEW
Transaction overview section provides overview for an order at a glance. This section contains information about sales transaction, 3-D Secure check and card
In case of payment failure this section will provide the error details if available from API response
ALIAS MANAGER
Alias Manager allows your customer to save the credit card information and to reuse the saved information for future payments.
Saferpay Secure Card Data, or SCD for short, is a service for saving sensitive payment means information in the certified Saferpay data center. By using SCD, the payment data is separated from the merchant application and no longer comes into contact with it. The stored secure Card data can be referred from future payments initiated via Transaction” interface.
This feature is available for payment methods that supports secure card data. Sensitive payment data is stored only in certified Saferpay data centre. If the settings, “Register alias and use during checkout” is enabled, logged in customers can save and use their card for future transactions.
In addition to this, customer can manage the saved cards from his customer account.
A new tab “Saved Cards” is added in the My Account page of Magento from which customers can add, update and delete cards from his account.
Customer can enter and submit the card data in Saferpay hosted card entry form from the account page. If additional security check is required so as to perform actions like 3D Secure and/or DCC, a Saferpay page will be opened in Lightbox
Card Number – Displays the masked credit card number provided by Saferpay
Payment Method – Saved card type.
3-D Secure Checked – For some cards like Saferpay do 3D secure check while adding cards. Such cards can be identified from here. Please note that only 3D secured cards can be used for recurring payments if the general settings “Recurring SCA challenge for PSD2 Compliance” is enabled.
Customers have the option to update the expiry date of the card that is already saved.
BACKEND ORDERS
Saferpay payment methods can be used for creating orders from Magento backend. The payments can be processed only through Transaction Interface. So please be careful about the authorization method you opted for corresponding payments.
Follow below steps to create order using backend
1. Go to Admin Panel > Sales > Orders and press the Create New Order button.
2. Choose the customer you want to create the order for.
3. Once you've selected a customer you need to choose which store view you want the order to be created on.
4. Add products to order
5. Enter Customer Address Information
6. Choose the payment and shipping methods
You will be redirected to payment gateway after submitting order
7. After reviewing the order click on “Submit Order” button.
8. The browser is redirected to the payment gateway. The merchant proceeds to payment by filling in the card details transmitted by the buyer and completes the transaction
9. After successful payment the browser is redirected to the order detail page.
CRON FOR CLEARING ABANDONED ORDERS
When the buyer has not completed the payment and the payment session has expired the order will be in “pending payment” state. A cron is automatically setup for clearing those orders.
As for all the other extensions, make sure you have configured and activated the job scheduler (crontab) as explained in the Magento documentation:
ERROR LOGS
Error Log section provides information about transactions performed by Saferpay that could not be completed successfully.
Error details provided by payment gateway will be logged and displayed under System > Configuration > Sales > Saferpay Error Log section.
RECURRING PAYMENT MODULE
COMPATIBILITY WITH AMASTY RECURRING PAYMENT EXTENSION
This extension offers subscriptions alongside regular products to trigger long-term repeat sales. It allows customers to simultaneously purchase both regular products and subscriptions.
Please refer https://amasty.com/docs/doku.php?id=magento_2:subscriptions-recurring-payments for more information about the extension.
We have implemented Saferpay Magento module to be compatible with the Amasty Recurring payment extension version 1.6.8 . After installing the Saferpay and Amasty recurring payment module, all of the Saferpay payment methods will get listed in the Amasty Recurring supported payment gateway list. Only the selected payment methods will be listed in the checkout page for subscription orders.
The following Saferpay payment methods are supported for subscription orders.
1. VISA
2. MASTERCARD
3. MAESTRO – Payment possible only if there is already saved card data available
4. AMERICAN EXPRESS
5. BANCONTACT – Payment possible only if there is already saved card data available
6. DINERS
7. JCB
8. BONUS CARD
9. MYONE
10. CREDIT CARD (SAFERPAY FIELDS)
The child subscription orders are created through amasty cronjob. The cronjob is executed every minute and new subscription orders are placed when the scheduled time arrives. If the subscription payment fails, then the subscription gets cancelled. In case of payment failure due to Soft Decline, a mail will be send to customer notifying about the authentication error.
The payment details are saved in the Saferpay account and not managed inside Magento, thus Saferpay module provides complete security of the sensitive payment details of the customers.
LIMITATIONS IDENTIFIED WITH THE AMASTY EXTENSION
Limitation 1: Cannot place the order when the order total is zero
Steps to Reproduce:
1] Access shop backend
2] Navigate to Stores > configuration > sales > amasty extension
3] Enable free shipping for subscription products, Free trial is enabled and charge initial fee is NO
4] Ensure that payment method “ZERO SUBTOTAL CHECKOUT” is enabled
5] Try to create an order with a subscription product
6] Observe that user cannot place the order when the order total is zero
Limitation 2: On creating an order with Grouped subscription product, the order is created as normal order instead of the subscription
Steps to Reproduce:
1] Access the shop as a customer.
2] Navigate to the grouped product, ensure subscription is enabled for the same.
3] Add to cart & Proceed the order.
4] Complete order creation
5] Check the customer account page.
6] The order is not listed @ "My subscription" in the customer account page
Limitation 3: Initial subscription fee for subscription orders with a configurable product or bundle products is wrong
Steps to Reproduce:
1] Enable Initial subscription fee.
2] Create a subscription order with a configurable product or bundle products
3] Observe the initial fee subscription in the total summary of the cart page
Limitation 4: Initial subscription fee is displayed in all subscription mails even though this is not valid for the further subscription orders
Steps to Reproduce:
1] Enable Initial subscription fee.
2] Create a subscription order.
3] Observe the subscription mail of the second subscription and further subscription orders.
4] The initial fee is displayed in the mail even though it is not valid.
API SPEC VERSION UPDATES
1.19 to 1.23
- WL Crypto Payments integration in the Saferpay Payment Page
- Added Klarna Payments support for Italy and France
- New currencies for SOFORT-PLN, HUF und CZK added
- New logo updated for Bancontact and iDeal payments
- EPS Refunds supported
- Removed Bonus Card payment
1.23 to 1.24
- Implementation of refunds of crypto payments
- Soft decline handling of recurring transaction
- Management API: Added configuration in Magento backend to create Saferpay Fields access tokens via API
- Added notification URLs in Transaction/Initialize
- Support for Fraud intelligence business
- Pre-authorizations and multipart-captures for additional brands (American Express, Diners Club International / Discover Card, JCB)
- Klarna Payments: Support for extended merchant data
- SuccessNotifyUrl and FailNotifyUrl in PaymentPage/Initialize
- Support of additional payment page languages (Bulgarian and Icelandic)
- Saferpay Fields improvements
Last modified 6mo ago
Copy link
Contents
ABOUT DOCUMENT
ABOUT MAGENTO MODULE
REQUIRMENTS
INSTALLATION
CONFIGURATION
GENERAL CONFIGURATION
PAYMENT METHOD SPECIFICS
PAYMENT METHOD SPECIFIC CONFIGURATION
SAFERPAY FEATURES
DESIGN CUSTOMIZATION
ORDER MANAGEMENT
CAPTURE PAYMENT
MULTIPART CAPTURE
CANCEL PAYMENT
VOID PAYMENT
REFUND PAYMENT
TRANSACTION OVERVIEW
ALIAS MANAGER
BACKEND ORDERS
CRON FOR CLEARING ABANDONED ORDERS
ERROR LOGS
RECURRING PAYMENT MODULE
LIMITATIONS IDENTIFIED WITH THE AMASTY EXTENSION
API SPEC VERSION UPDATES
1.19 to 1.23
1.23 to 1.24