Apple Pay

Apple Pay transactions can be processed via the Saferpay Payment Page without much effort from your side. Note that Apple Pay is not a classic means of payment, but rather a digital wallet. Your customers will still pay with Visa, Mastercard, or whatever credit card has been saved inside the wallet, thus the actual recorded payment method will correspond to this. However, Saferpay will also return information that this transaction has been performed through Apple Pay. Furthermore, all options and limitations of the used means of payment apply if not mentioned otherwise in this chapter.

The following chapter will guide you through the steps required in order to activate and use Apple Pay.

General Requirements

The handling of Apple Pay payments with Saferpay requires:

• A corresponding license and thus a valid identification with a username and password for the Saferpay system.

• Availability of at least one active Saferpay terminal by which payments can be carried out and availability of the associated Saferpay TerminalId.

Technical requirements

The general integration of Apple Pay can only be done via the Payment Page or via server-to-server communication and requires the following things to be noted:

• Apple Pay is only available with SpecVersion 1.15 or higher.

• The notification URLs inside the Notification container are mandatory in order to avoid missing payment successes. See the Payment Page process for further information.

• Apple Pay specifically will not be displayed if the Payment Page is opened in an iframe without using the attribute allow="payment". It also needs additional configuration. Please see the chapter iframe integration below.

• Apple Pay does not support the usage of the Address Form on the Payment Page. Even if requested, no form will be displayed when Apple Pay is selected. However, you can acquire the address saved inside the wallet itself, e.g. for an Express Checkout, gathering the payer's address this way.

• The Condition parameter does not work with Apple Pay transactions.

Supported features

Since Apple Pay is not a classic payment method but a digital wallet, the supported features depend on the payment means that are used.

Furthermore, the merchant can only accept payment methods that are activated on the specified terminal ID.

The payment means within the wallet are then processed via the normal processors.

For example: If a cardholder selects his Visa card, the card is then processed as such through Apple Pay as the wallet.

The exception to this rule are Mail Phone Order (MOTO) and Dynamic Currency conversion (DCC), which are both not supported.

Activation

The activation of Apple Pay for your Saferpay account, be it live or on the test environment, requires next to no effort and can be done in a matter of seconds.

However, there are two options available to you that represent the two integration methods available to you.

Payment Page

The first option represents the integration through our Payment Page and is the easiest way of using Apple Pay.

Business

The second option represents the integration through our transaction interface, also called a Server-to-Server integration, which requires more effort but also offers more flexibility on your end.

You have to decide first which option you want to use – you can use both if you want – and then proceed to the activation itself:

Payment Page

1 - The first step is to log into the Saferpay Backoffice. There, you have to navigate to the Settings tab and click on Payment Means / Terminals.

2 - Next, select the e-Commerce or Secure PayGate terminal on which you want to activate Apple Pay.

3 - Navigate to the Self Service section; there you will find Apple Pay.

4 - Activate Apple Pay for the Payment Page.

5 - You will be prompted with another window that asks you to accept the Terms and Conditions from Apple. Mark the checkbox and click Activate.

(click to enlarge)

6 - And you are done! Apple Pay is now available for you on your Saferpay Terminal.

(click to enlarge)

Server-to-Server

#1: Log into the Saferpay Backoffice and navigate to Settings > Terminals. There, you need to select the desired terminal on which you want Apple Pay to be activated.

#2: Scroll down to the Self Service section until you see Apple Pay and activate it for Transaction Interface use.

Please do not use the Simulator, as that would cause the Apple test cards to work incorrectly.

#3: You will be prompted with a window asking you to accept Apple's terms and conditions. If you do, click the box and then on Activate.

#4: Once you have activated Apple Pay, you need to configure it. For that, you have to click on Configure.

#5: You will be prompted with the configuration window.

In order to be able to authorize Apple Pay payment tokens, Saferpay must be able to decrypt said tokens. This is done using a certificate which first must be created, following these steps:

1. Download the Saferpay Certificate Signing Request (CSR).

2. Use this CSR to create the Payment Processing Certificate itself. Please follow this guide in order to do so.

3. Upload the certificate to Saferpay.

4. All done!

The Payment Processing Certificate is not the same as the Merchant Identity Certificate. Only the former is needed for Saferpay.

Only one Certificate per CustomerId is needed. Even if you have multiple terminals on that account, you only do this step once and can then use the certificate for any other terminal on that account.

Integration

Payment Page

The Payment Page integration follows the normal flow and guidelines as described here. The handling of all Apple Pay related aspects – calling the Apple Pay API, displaying information, 3D Secure, etc. – will be done by the Payment Page automatically and thus is none of your concern!

However, there are some optional features you can implement outside of the normal Payment Page flow.

Direct pre-selection

If you want to directly select Apple Pay, you have to use the parameter Wallets within the PaymentPage Initialize request!

{
    "RequestHeader": {
        "SpecVersion": "[CURRENT SPECVERSION]",
        "CustomerId": "[YOUR CUSTOMERID]",
        "RequestId": "[YOUR REQUESTID]",
        "RetryIndicator": 0,
        "ClientInfo": {
            "ShopInfo": "My Shop",
            "OsInfo": "Windows Server 2016"
        }
    },
    "TerminalId": "[YOUR TERMINAL]",
    "Payment": {
        "Amount": {
            "Value": "12345",
            "CurrencyCode": "EUR"
        },
        "OrderId": 123,
        "Description": "Test Order #123"
    },
    "Wallets": [
        "APPLEPAY"
    ],
    "PaymentMethods": [
        "VISA",
        "MASTERCARD"
    ],
    "ReturnUrl": {
        "Urls": "[YOUR URL]"
    },
}

Due to restrictions from Apple, Saferpay is not allowed to directly select Apple Pay! If you use this method, Apple Pay will be displayed on the Payment Page with the user having to select it.

If you are using "PaymentMethods", you must also submit "Wallets" if you want Apple Pay to be displayed. Also, if you are just submitting one payment method, the Payment Page will still directly jump to the card entry form, skipping Apple Pay.

If you are using "Wallets" alongside "PaymentMethods", you can limit the brands that your customers can use. However, note that the Payment Page will also display the given brands as dedicated payment methods, so the customer might pay this way instead of using Apple Pay.

iframe Integration

If you intend to use Apple Pay via the Payment Page inside an iframe, said iframe must have the attribute allow="payment" attached to it. Otherwise the payment will not be possible.

You also need to make sure that your server is set up according to Apple's documentation. Otherwise the verification request may fail.

Next, you have to upload the so-called "domain-verification file" from Saferpay and add it to your domain.

You can download the file here.

The file must be publicly available on your server, under the following path:

https://[YOUR_DOMAIN]/.well-known/apple-developer-merchantid-domain-association

Saferpay checks its availability during activation. If it is not present, no domain name (see further below) can be saved, so make sure that this step has already been done.

Please note that this file may need a yearly update.

Furthermore, the iframe integration requires you to enter your top-level domain inside the Saferpay Backoffice.

For that, navigate back to your Apple Pay activation and click on Configure.

On the following screen, you must enter the hostname of the top window in which the iframe is embedded.

Click on Save and you are done.

Apple Pay Server-to-Server

Saferpay also offers the option for you to integrate Apple Pay directly into your application. This allows a more integrated and seamless solution, as it does not require the usage of the payment page, thus also circumventing its limitations (see above).

This requires an Apple Developer account! If you do not have one already, please create one and then come back to this guide!

Please follow the following steps in order to directly integrate Apple Pay.

1 - Setup

Before you can start integrating and testing Apple Pay, you first need to set it up, as described here.

2 - Apple Pay Integration

Once the setup is done, you can go ahead and integrate Apple Pay. It is important to know that at this stage, you are directly integrating the Apple Pay widget here and not Saferpay. Apple Pay covers the gathering of your clients account data, while Saferpay will use it to create a transaction.

This also means that your integration underlies all the terms and conditions, rules and guidelines defined by Apple! Please refer to the Apple Pay documentation below for further information!

Apple has extensive documentation on how to achieve it for different use cases. For example, a normal web checkout, but other integrations, like iOS apps, are also possible.

The important thing is that you have to integrate Apple Pay to the point where you gather the Base64-encoded Apple Pay Payment Token, which then needs to be passed to Saferpay.

3 - Submitting the token to Saferpay

Once you have the token, you need to submit it to the Saferpay payment gateway. In order to do so, you first need to pass the token to your backend so it may be used in a server-to-server request.

How you do this is up to you. You could use a normal POST, an AJAX method, or other means to do so.

However, never integrate the server-to-server communication to Saferpay on the client side, as it requires the Saferpay API credentials to be present. These could be extracted at this point, allowing an attacker easy access to your account!

Especially in the case of mobile apps, we recommend a client-server model, as described here.

Never store sensitive data and credentials on the client side!

This is done via the Transaction Interface.

You have to submit the payment token to Saferpay, which is easily done by putting it into the PaymentMeans.ApplePay.PaymentToken parameter with the Transaction Initialize request.

Apple Pay will report a RedirectRequired: false with the initialization response, as a redirect is not necessary. Thus, you can skip ahead and continue with the authorization.

Alternatively, if you want to limit the amount of requests to a minimum, you can also use AuthorizeDirect, reducing the amount of requests to one; the parameters, however, stay the same, with one addition:

When using AuthorizeDirect, you must set the parameter Initiator to "PAYER" in order to flag this transaction as a Customer Initiated Transaction (CIT). Not doing so will lead to rejections.

If you intend to also integrate Google Pay Server-to-Server, we recommend doing it via the Transaction Interface method, as Google Pay requires it. This streamlines your integration and cuts down on your integration effort for both.

Data formatting

The Apple Pay widget will send you all kinds of data; however, Saferpay only needs the following parameters and their content:

{
    "data": [PAYMENT DATA],
    "signature": [TOKEN SIGNATURE],
    "header": {
        "publicKeyHash": [HASH],
        "ephemeralPublicKey": [KEY],
        "transactionId": [ID]
    },
    "version": [VERSION]
}

This data then needs to be Base64-encoded before being submitted to Saferpay.

Testing

Saferpay does offer an extensive Apple Pay simulator. All test cases are controlled through the simulator UI. Unlike production you do not need an Apple device to test Apple Pay!

Please refer to the Activation section to see how to activate Apple Pay on the test environment.

Note that the server-to-server method does not use the Saferpay simulator, but instead needs special test cards provided by Apple, which you can find over here.

Please note: Only the Mastercard PANs are supported at this point!