Saferpay

The Saferpay integration supports several payment methods through Saferpay by Worldline (formally SIX Saferpay), including methods like TWINT particularly for the Swiss market.

Multi-merchant	Multi-currency

Payment Method	One-time	Recurring	Refunds
Card
PostFinance Card
PostFinance E-finance
TWINT
Bitcoin
Ethereum
Apple Pay
Google Pay

To fully enable E-Finance, PostCard or TWINT methods in your Saferpay test environment, you may need to contact Saferpay support. TWINT recurring payments, for instance, requires a business contract with Secure Alias Storage and TwintMerchantInitiatedPayment (User On File) enabled on your terminal.

Pre-requisites

FinDock installed and configured
A successful connection to WebHub

Install Saferpay extension

Follow the standard procedure for installing payment processors to add the Saferpay payment extension and activate payment methods.

Check and assign the required permissions. If you are using custom permission set groups, ensure the package-specific permission sets are assigned.

Configure Saferpay

Configuring the Saferpay extension requires setting up a test account with the Saferpay Backoffice and a production account with Saferpay myPortal. Some information from your Saferpay settings needs to be copied to the Saferpay for FinDock extension settings, so you will need to have both applications open to complete the configuration.

To configure Saferpay for FinDock:

Launch the FinDock app and click the FinDock Setup tab.
Go to Payment Processors & Methods.
Under Installed Processors, click the Saferpay processor entry.
Click Add account.
Fill in the initial settings.
- Name: Add a name for the Saferpay account (distinguishable from other targets).
- Notification URL: this is automatically filled by FinDock and shown on the target once you save the target. This is used by Saferpay to send event messages to FinDock.
- Default Account: enable if this account should be used as the default account for Saferpay payments.
- Is Test: enable if you are setting up a test target.
In a separate tab, register or log in to the Saferpay Backoffice at https://test.saferpay.com/BO/. If you are configuring a production org, use the Saferpay myPortal: https://myportal.six-payment-services.com/merchantportal/
Click the Settings tab and then click JSON API basic authentication.
When you created your back office account, you received an email from Saferpay with an JSON API username and password. If you no longer have this email, click Create new JSON API login to get a new login username and password.
Copy-paste your JSON API login username and password into the corresponding fields in the Saferpay extension settings in FinDock.
In the Saferpay portal, to to the Terminals settings under Payment Means.
Copy-paste your Customer ID and eCommerce Terminal ID into the corresponding fields in the Saferpay extension settings in FinDock.
Adjust the FinDock extension settings as needed.
- Use Secure Alias Storage: if your Saferpay contract includes the Secure Card Data module, enable this setting to use credit card aliases. NOTE: This setting is required when using TWINT recurring payments.
- Log Requests: activate if you want to log all Saferpay connection events. This can be helpful with debugging during testing, for example.
Click Save when you are done.

Special handling for one-time vs. recurring

With Saferpay payment methods that support recurring payments, you use payment schedules to collect future installments of the recurring payment as normal.

In addition, for one-time payments made with the PostFinance PostCard method, you also need to run a payment schedule to collect the one-time payment.

Although the PostCard payment flow itself is similar to a normal credit card, the payment is made via direct debit. This requires its own set of instructions that FinDock sends the Saferpay API using the payment schedule process.

To enable recurring payment collection with TWINT, you need to have TwintMerchantInitiatedPayment (User On File) enabled on your terminal and a Saferpay Business contract with Secure Alias Storage. Please contact Saferpay support for assistance.

To collect TWINT recurring payments, FinDock creates a payment profile with the following details. No more details are provided by Saferpay & TWINT to FinDock:

Brand = TWINT
Wallet Type = TWINT
Record Type = Credit Card

No payment profile is created for one-time payments with TWINT, since no relevant data is provided and no payment profile & mandate combination is needed for future collection.

Payment profile deduplication is based on a combination of the Contact Id and Wallet Type, (i.e. only one TWINT wallet for each contact).

Special considerations for mandate references

To support Saferpay Secure Card Data capabilities, the Mandate object uses an Is Alias checkbox field. FinDock uses the checkbox to determine if the reference is an alias or a regular reference. By default, Is Alias is checked (true) for new recurring credit card payments.

The FinDock integration to Saferpay includes RegisterAlias in all initial recurring payment callouts. This stores the alias on the Saferpay side. In FinDock, the alias on stored on the mandate reference field.

When you run a payment schedule, FinDock handles the callouts as required for both regular and alias references based on the Is Alias field.

If you are migrating recurring credit card payments to Saferpay from another PSP, you must set Is Alias to true to be able to process further installments through Saferpay.

Special considerations for cryptocurrency

When initiating cryptocurrency payments, the amount must use Swiss Franks (CHF) for the currency. FinDock automatically validates the currency and throws and API exception error if the ISO currency code is not CHF.

For further information, please refer to the Saferpay Documentation about cryptocurrency requirements.

Special considerations for Apple Pay and Google Pay

These digital wallet methods are treated as card payments by Saferpay. Please refer to their documentation for Apple Pay and Google Pay for details on how these payments are processed. These options need to be enabled in your Saferpay back office account, but no additional configuration is needed in the FinDock extensions (no separate payment methods to enable).

The payment profile associated with Apple Pay or Google Pay uses the credit card record type. The Wallet Type field indicates which digital wallet is used.

For recurring payments with Apply Pay or Google Pay, you collect future installments using payment schedules. These installments are automatically included in payment schedules with PaymentHub-Saferpay as the payment processor and CreditCard as the payment method.

Payment API messages

You can use the following example messages to test if the Saferpay configuration is working as expected.

One-time payment with credit card

{
    "SuccessURL": "https://www.example.com/success",
    "FailureURL": "https://www.example.com/error",
    "Payer": {
        "Contact": {
            "SalesforceFields": {
                "FirstName": "Eric",
                "LastName": "Johnson",
                "Email": "eric@johnson.com"
            }
        }
    },
    "OneTime": {
        "Amount": "30"
    },
    "PaymentMethod": {
        "Name": "Creditcard",
        "Processor": "Six-saferpay-for-findock"
    },
    "Settings": {
        "SourceConnector": "PaymentHub"
    }
}

Recurring payment with PostFinance card

{
    "SuccessURL": "https://www.example.com/success",
    "FailureURL": "https://www.example.com/error",
    "Payer": {
        "Contact": {
            "SalesforceFields": {
                "FirstName": "Eric",
                "LastName": "Johnson",
                "Email": "eric@johnson.com"

            }
        }
    },
    "Recurring": {
          "Amount": "25",
          "Frequency": "Monthly",
          "StartDate": "2020-11-01"
     },
    "PaymentMethod": {
        "Name": "PF PostCard",
        "Processor": "Six-saferpay-for-findock"
    },
    "Settings": {
        "SourceConnector": "PaymentHub"
    }
}

One-time payment with PostFinance E-finance

{
    "SuccessURL": "https://www.example.com/success",
    "FailureURL": "https://www.example.com/error",
    "Payer": {
        "Contact": {
            "SalesforceFields": {
                "FirstName": "Eric",
                "LastName": "Johnson",
                "Email": "eric@johnson.com"
            }
        }
    },
    "OneTime": {
        "Amount": "30"
    },
    "PaymentMethod": {
        "Name": "PF e-finance",
        "Processor": "Six-saferpay-for-findock"
    },
    "Settings": {
        "SourceConnector": "PaymentHub"
    }
}