Interfaces
Integration Guide
Apple Pay
Apple Pay transactions can be processed via the Saferpay Payment Page, without much effort from you 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.
Requirements
The handling of Apple Pay payments with Saferpay requires:
- The corresponding Saferpay eCommerce licence and thus the existence of 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.
Supported features
Since Apple Pay is not a classical Payment Method, but a digital Wallet, the supported features depend on the payment means, that are saved within the Wallet.
Due to an ongoing dispute between Apple and Visa, every transaction made through Apple Pay, using a Visa credit card, will result in a transaction with no liability shift! Please consider this during implementation!
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:
1 - First step is to log into the Saferpay Backoffice, there you have to navigate to the Settings tab and click on Payment Means / Terminals.
(click to enlarge)
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 either for the Payment Page, or for the server to server Business flow (please see this chapter further down).
5 - You will be prompted with another window, which 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)
Integration
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
Notificationconatiner are mandatory, in order to avoid missing payment successes. See the Payment Page process for further information. - Apple Pay can only be used with Apple devices, like Macs, iPhones and iPads. Exception being the test environment, so you are able to test Apple Pay on other devices.
- Furthermore, only Apple's own browser, Safari, is supported. Exception being the test environment, so you are able to test Apple Pay using other browsers.
- Apple Pay does not support Secure Card Data, even though the means of payment may support it. However Recurring Payments can be executed, if supported by the payment means.
Recurring Payments can only be executed, via the Referenced Transactions Method, as it does not support Secure Card Data, as previously mentioned.
- Apple Pay specifically will not be displayed, if the Payment Page is opened in an Iframe, due to restrictions emposed by Apple. Thus, you must make sure, that you do not open the Payment Page in an Iframe, if you want to use Applepay.
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 redirect
If you want to perform a direct redirect to Apple Pay, you have to use the parameter Wallets within the PaymentPage Initialize request!
1
{
2
"RequestHeader": {
3
"SpecVersion": "[CURRENT SPECVERSION]",
4
"CustomerId": "[YOUR CUSTOMERID]",
5
"RequestId": "[YOUR REQUESTID]",
6
"RetryIndicator": 0,
7
"ClientInfo": {
8
"ShopInfo": "My Shop",
9
"OsInfo": "Windows Server 2016"
10
}
11
},
12
"TerminalId": "[YOUR TERMINAL]",
13
"Payment": {
14
"Amount": {
15
"Value": "12345",
16
"CurrencyCode": "EUR"
17
},
18
"OrderId": 123,
19
"Description": "Test Order #123"
20
},
21
"Wallets": [
22
"APPLEPAY"
23
],
24
"PaymentMethods": [
25
"VISA",
26
"MASTERCARD"
27
],
28
"ReturnUrls": {
29
"Success": "[YOUR URL]",
30
"Fail": "[YOUR URL]",
31
"Abort": "[YOUR URL]"
32
},
33
}
Copied!
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 which your customers can use. However, note that the Payment Page also will display the given brands as dedicated payment methods, so the customer might pay this way instead of using Apple Pay.
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.
This requires an Apple developer account! If you do not have one already, please create one and then come back to this guide!
Furthermore, you'll also need a Saferpay Business license, in order to access the necessary API functions!
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. This is necessary, so Saferpay can decode the Apple Pay payment tokens and extract the payment means for further processing safely.
#1: Log into the Saferpay Backoffice and navigate to Settings > Terminals. There, you need to select the desired terminal, you want Apple Pay to be activated on.
#2: Scroll down to the Self Service Section, until you see Apple Pay and activate it for Business use.
#3: You will be prompted with a window, asking you to accept Apples 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! Please continue to the next step.
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 an 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 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!
Never store sensitive Data and Credentials on client-side!
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. Thusly, 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.
If you intent on also integrating Google Pay Server-to-Sever, 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.
All done. You have just executed an Apple Pay server-to-server transaction. Note, that this transaction also needs to be captured, in order to finalize the payment and initiate the money-flow.
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, or browser, to test Apple Pay!
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 Visa and Mastercard PANs are supported at this point!
Last modified 3d ago