Apple Pay integration

Introduction

Sherlock's is a secure multi-channel e-commerce payment solution that complies with the PCI DSS standard. It allows you to accept and manage payment transactions by taking into account business rules related to your activity (payment upon shipping, deferred payment, recurring payment, payment in instalments, etc.).

The purpose of this document is to explain the Apple Pay means of payment integration into Sherlock's.

Who does this document target?

This document is intended to help you implement the Apple Pay means of payment on your e-commerce site.

It includes:

functional information for you
implementation instructions for your technical team

To get an overview of the Sherlock's solution, we advise you to consult the following documents:

Functional presentation
Functionality set-up guide

Understanding Apple pay payments with Sherlock's

General principles

Apple Pay is a means of payment offered by Apple to issue payments in a simple and secure way on iPhone, iPad, Apple Watch or Mac client, without card or cash.

The cardholder has previously added their card to the wallet available on the various Apple devices. Afterwards, they can pay for purchases on a website or on a mobile application.

With this solution, customers pay for their purchases online without having to enter their card details all the time. In addition, with the wallet application they can view their transaction history.

Acceptance rules

Available functionalities

Payment channels
Internet	V	Default payment channel
MAIL_ORDER, TELEPHONE_ORDER	X
Fax	X
IVS	X
Sherlock’s In-App	X

Means of payment
Immediate payment	X
End-of-day payment	V	Default method
Deferred payment	V	Limited to 6 days.
Payment upon shipping	V	Limited to 6 days.
Payment in instalments	X
Subscription payment	X
Batch payment	X
OneClick payment	X

Currency management
Multicurrency acceptance	V
Currency settlement	X
Dynamic currency conversion	X

Apple Pay means of payment characteristics

Here are the rules applied to Apple Pay:

Feature	Restriction	Restriction by
Means of payment	CB* MASTERCARD MAESTRO VISA VPAY ELECTRON	Sherlock's
Browser/Device	Device Apple	Apple
IFrames	No	Apple

(*) Depends on the issuer.

You have to make sure your acquirers support the Apple Pay flow.

All anti-fraud checks are supported under Apple Pay payments (fraud tool).

Apple imposes a graphic charter for the payment page. Information related to this charter is available here: https://developer.apple.com/apple-pay/marketing/

Attention: the security code is not populated in the Apple Pay payment process.

Authentication request

During the payment process, the cardholder authentication is done by Apple Pay.

You have two options:

You wish to manage yourself the cardholder authentication.
For this purpose, you will need to open an account with Apple Pay and complete the implementation to manage the Apple Pay authentication. Details about the implementation of authentication with Apple Pay can be found here: https://developer.apple.com/documentation/apple_pay_on_the_web/
You will need to use the Sherlock’s Office interface.

You wish to delegate the whole transactional process to the Sherlock's platform and in particular the cardholder authentication to the Apple Pay server.
In this case, you will need to use the Sherlock’s Paypage interface.

Authorisation request

The maximum capture delay allowed for an Apple Pay payment is 6 days.

If you enter a longer capture delay, it will be automatically forced by the payment platform.

Payment remittance in the bank

Payments are remitted to a bank according to the payment terms you set. As standard, the remittance in bank is triggered at night as from 10 pm CET (Central European Time) via a file exchange with the acquirer.

Signing your Apple Pay acceptance contract

You have two options to offer the Apple Pay means of payment on your website:

You wish to manage yourself the cardholder authentication and use the Sherlock's platform to make the authorisation request and the bank remittance. You will need to contact Apple Pay.
You wish to delegate the whole transactional process to the Sherlock's platform and in particular the cardholder authentication with Apple Pay server, the authorisation request and the bank remittance.
In this case, you have no interaction with Apple Pay. Sherlock's is responsible for your enrollment/activation with Apple Pay.

In order to offer the CB means of payment on your website, you have to sign a Sherlock's contract.

Making an Apple Pay payment

The remittance modes available for an Apple Pay transaction are:

Cancellation mode: default mode allowing transaction remittance on a predefined date, called capture delay. When this capture delay is reached, the remittance is sent automatically. This delay is set via the captureDay field with its 0 default value (end-of-day payment).
Validation mode: you must validate the transaction to trigger the remittance. A capture delay must also be defined. When this capture delay is reached or exceeded, you will not be able to validate the transaction, which will therefore expire automatically.

The diagram below explains the different transaction statuses according to the chosen capture mode:

Description des status possibles pour une transaction Apple Pay

Making an Apple Pay payment with Sherlock’s Paypage

The payment process for Sherlock’s Paypage is described below:

Steps of an Apple Pay payment via Paypage

Verifying the compatibility of the user device (optional)

This step is to be used only if you want to have the payment mean selection page before Sherlock’s Paypage. You can verify that the user device supports Apple Pay before starting a Sherlock’s Paypage payment. To do this, you can include a Javascript library provided by Sherlock's in your Web application and call its isApplePayAvailable function.

URL to the library:

For the production environment: https://resources.sips-services.com/rsc/applepay/js/device_verification.js
For the test environment: https://resources.test.sips-services.com/rsc/applepay/js/device_verification.js


    <script type="text/javascript" src="<LIBRARY_URL>" id="sdpx-verify-applepay"></script>
    <script>sdpx.isApplePayAvailable().then(result => {
		if (result.responseCode === "00") {
		  // ApplePay is available
		}
	  }</script>

Tip: By default, importing the library using a script tag will make it available in the global variable sdpx, as shown in the example above. You can also use RequireJS to import the module and call its function.

IMPORTANT: The source code of the SDPX JavaScript library must not be installed on your server but must be retrieved for each transaction using the URL provided above.

The isApplePayAvailable function returns a promise, which returns an object containing the following fields:

responseCode: a simple code that describes the result of the verification.
reason: a more detailed description of the verification.
version: the ApplePay version compatible with the device.

The responseCode field will give you a clear result of the verification. It may have the following values:

Response Code	Value of "reason"	Meaning
00	ApplePay is supported.	Compatible. The device supports ApplePay.
01	No compatible ApplePay versions found. User likely has a recent device not supporting our known versions.	Incompatible: version. The device supports ApplePay, but the versions of ApplePay supported by the device aren't known by Sherlock's. ApplePay will not be available on Sherlock’s Paypage.
02	User device does not support ApplePay API.	Incompatible: device. The device does not support ApplePay.
99	Error during ApplePay detection: <Error message>	Error. There was a technical error during the verification.

Setting the payment request

The following field has a particular behaviour:

Field name	Remarks/rules
captureDay	The value sent in the request must be 6 at a maximum. A larger value will be forced to 6.

Analysing the response

The following table summarises the different response cases to be processed:

Status	Response fields	Action to take
Payment accepted	`acquirerResponseCode` = 00 `authorisationId` = (cf. the Data Dictionary). `paymentMeanBrand` = card used in the wallet (VISA, MASTERCARD, CB or other). `paymentMeanType` = CARD `paymentMeanDataProvider` = APPLEPAY `responseCode` = 00	You can deliver the order.
Acquirer refusal	`acquirerResponseCode` = (cf. the Data Dictionary). `responseCode` = 05	The authorisation is refused for a reason unrelated to fraud, you can suggest that your customer pay with another means of payment by generating a new request.
Client device incompatible with Apple API or invalid request	`responseCode` = 12	Propose an alternative payment method to the customer to pay for the order.
Refusal due to a technical issue	`acquirerResponseCode` = 90-98 `responseCode` = 90, 99	Temporary technical issue when processing the transaction. Suggest that your customer redo a payment later.

For the complete response codes (responseCode) and acquirer response codes (acquirerResponseCode), please refer to the Data dictionary.

Making an Apple Pay payment with Sherlock’s Office

The payment process for Sherlock’s Office is described below:

Steps of a Masterpass payment via Paypage

Setting the payment request

To make a payment with Sherlock’s Office, you must use the cardOrder method.

The Apple Pay payment request includes all mandatory fields of the connector you are using.

The following fields have a particular behaviour:

Field name	Remarks/rules
panEntryMode	OEMPAY
paymentMeanDataProvider	APPLEPAY
authenticationResult.applePay.cavv	The security code provided by Apple Pay.
authenticationResult.applePay.eci	The ECI indicator provided by Apple Pay.
authenticationResult.holderAuthentProgram	APPLEPAY
paymentMeanBrand	Must be populated with the card brand (CB, Visa, Mastercard, …).
cardNumber	Provide the DPAN (= Apple Pay card number).
cardExpiryDate	Provide the DPAN expiry date.
orderChannel	INTERNET or INAPP
walletType	Should not be populated.
schemeTokenData.tavv	The security code provided by Apple Pay. Replace the usage of field authenticationResult.applePay.cavv (still usable) for CB2A 161 protocol

Analysing the response

The following table summarises the different response cases to be processed:

Status	Response fields	Action to take
Payment accepted	`acquirerResponseCode` = 00 `authorisationId` = (cf. the Data Dictionary). `paymentMeanBrand` = card used in the wallet (VISA, MASTERCARD, CB or other). `paymentMeanDataProvider` = APPLEPAY `responseCode` = 00	You can deliver the order.
Acquirer refusal	`acquirerResponseCode` = (cf. the Data Dictionary). `responseCode` = 05	The authorisation is refused for a reason unrelated to fraud, you can suggest that your customer pay with another means of payment by generating a new request.
Refusal due to a technical issue	`acquirerResponseCode` = 90-98 `responseCode` = 90, 99	Temporary technical issue when processing the transaction. Suggest that your customer redo a payment later.

For the complete response codes (responseCode) and acquirer response codes (acquirerResponseCode), please refer to the Data dictionary.

Managing your Apple Pay transactions

Available cash operations

The following operations are available on Apple Pay transactions:

Cash management
Cancellation	V	Cancellation available on the partial amount of the transaction.
Validation	V	Validation available on the partial amount of the transaction.
Refund	V	Refund available on the partial amount of the transaction and for amounts greater than the initial amount (unlimited refund).
Duplication	X

The diagram below allows you to know which cash management operation is available when a transaction is in a given state:

Diagram very complex to describe, please contact support sips@worldline.com

Viewing your Apple Pay transactions

Reports

The reports provided by Sherlock's allow you to have a comprehensive and consolidated view of your transactions, cash operations, accounts and chargebacks. You can use this information to improve your information system.

The availability of Apple Pay transactions for each type of report is summarised in the table below:

Reports availability
Transactions report	V
Operations report	V
Operations report	V
Chargebacks report	V

Note: for Apple Pay transactions, the paymentMeanBrand field is populated with the card brand (CB, Visa, Mastercard, …).

Sherlock's Gestion

You can view your Apple Pay transactions and perform various cash management operations with Sherlock's Gestion.

Here are the details of an Apple Pay transaction made with a card enrolled for OEM payments:

Capture of an Apple Pay transaction details

How to perform Apple Pay tests

To test Apple Pay, you need:

an Apple developer account to which you link a sandbox test account
an Apple device (list of compatible devices in the link above)

Connect your sandbox test account to your Apple device.

Add one of those cards in the Apple wallet linked to your test account.

Perform an Apple Pay payment using your Apple device.

The cents of the transaction amount allow to set the value of the Response Code.

If the amount YY,XX of the transaction has for euro cents XX equals 00 then the Response Code will be 00
If XX equals 05 the Response Code will be 05
If XX equals 99 the Response Code will be 99
For the other values, the Response Code code will be 00