--- title: "Apple Pay" description: "Apple Pay is Apple's digital wallet, allowing fast and secure payments from the devices of the Apple ecosystem. In this guide you will learn how to activate it, configure it on Fabrick Payment Orchestra and integrate it correctly into your e-commerce." url: "https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/alternative-payments/apple-pay/" language: "en" --- # Apple Pay ## Why choose Apple Pay Apple Pay is the **digital wallet developed by Apple**, allowing payments to be made simply, quickly and securely from iPhone, Apple Watch, iPad and Mac. Integrating it into your e-commerce widens the payment methods available and improves the user experience through a fast, frictionless checkout. It removes the need to enter card details manually and, thanks to **Face ID** and **Touch ID**, buyers authorise payments immediately with a single gesture. > **Further reading** > > For more information see the [official Apple documentation](https://developer.apple.com/apple-pay/) --- ## Services and features available through the Fabrick integration Integrating Apple Pay with Fabrick Payment Orchestra provides a complete set of features that simplify transaction management and improve the experience for both the merchant and the buyer. - **Compatible with apps and websites**: support for iOS apps through [PassKit](https://developer.apple.com/documentation/passkit/apple-pay) and for web integrations through [Apple Pay JS](https://developer.apple.com/documentation/apple_pay_on_the_web). - **Dedicated certificates**: upload of the Payment Processing Certificates directly from the Gestpay dashboard for the direct integration. - **Payment Token handling**: Fabrick handles the payment token itself, displaying Apple Pay on its own page with no additional development on the merchant's side. - **Tokenization**: the payment method can be tokenized and reused for subsequent charges (see [Tokenization](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/alternative-payments/apple-pay/#tokenization)). - **Recurring payments**: Apple Pay can be used as the payment method of a recurring series (see [Recurring payments](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/alternative-payments/apple-pay/#recurring-payments)). - **Native SCA**: Apple Pay's biometric authentication (Face ID / Touch ID) satisfies the SCA requirements, in most cases reducing the need for additional authentication ([find out more](https://developer.apple.com/support/sca/)). - **Fabrick Guaranteed Payments**: fraud prevention service supporting the merchant ([find out more](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/features/fraud-prevention/fabrick-guaranteed-payments/)). - **Simplified reconciliation**: payment management through dedicated reports ([find out more](https://www.fabrick.com/it-it/assistenza/fabrick-dashboard/)). - **Advanced transaction management**: support for partial and multiple captures and reversals, for flexible payment management. - **Multi-currency support**: Apple Pay accepts ISO 4217 currency codes; the currencies that can actually be processed depend on the configuration of your Fabrick profile. - **Support for international schemes**: Apple Pay through Fabrick supports Visa, Mastercard and American Express. --- ## Apple Pay on Fabrick Payment Orchestra: activation and integration types ### Activation request To start accepting Apple Pay payments, you can request the activation: - By contacting your sales representative - By contacting support at the following [link](https://landing.fabrick.com/fabrick-dashboard-support) Once the required procedures are complete: - Fabrick enables Apple Pay on the shop and informs the merchant. - You can verify that the payment method is active in the Dashboard, under **Workspace → Shops → \[Select shop] → Settings** ![Apple Pay activation in the Dashboard](https://docs.fabrick.com/en/assets/images/applepay-confirm-activation-01-1b7a466b9397cb0968f718a2e0a1f0cf.png) > **Activation complete** > > From this moment on, your e-commerce is ready to accept Apple Pay payments through Fabrick Payment Orchestra. ### Integration types Fabrick offers two integration types for Apple Pay: - **Hosted integration** ### Supported integrations ✓ — Checkout Page ✓ — Pay By Link ✓ — Web Component ✓ — Lightbox Apple Pay is displayed directly on the payment page. Fabrick handles the button, the token and the transaction processing, with an [additional configuration step](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/alternative-payments/apple-pay/#additional-configuration-for-web-component-and-lightbox) for **Web Component** and **Lightbox**. - **API integration** ### Supported integrations ✓ — API Only With this method Apple Pay is integrated directly into the website or app. It requires uploading the Apple certificates to the Gestpay dashboard, implementing the payment button, generating the token and sending it to Fabrick for processing. > **Testing Apple Pay in the sandbox environment** > > To run the tests you need an [Apple developer account](https://developer.apple.com/programs/) and an Apple device configured in **sandbox** mode with a [test card added to the Wallet](https://developer.apple.com/apple-pay/sandbox-testing/). --- ## Hosted integration **Apple Pay is displayed directly on the payment page**. Fabrick runs the Apple scripts and generates the payment token itself. ![Apple Pay on the Fabrick payment page](https://docs.fabrick.com/en/assets/images/applepay-checkout-page-01-ca16056d33c87aca237f35e2b2f5bbdf.png) The payment is available on **all browsers, including on non-Apple devices**. In this case a QR Code is shown, which lets the buyer complete the payment with an external Apple device: after scanning, the flow starts on the device and the transaction is processed by Fabrick. ![Apple Pay QR Code for payment from a non-Apple device](https://docs.fabrick.com/en/assets/images/applepay-checkout-page-02-1f191a1b012d28c7f3757713ffecd732.png) If the QR Code expires, you can **generate a new one** for the same transaction by clicking *Ricevi nuovo codice*. ![Regenerating an expired Apple Pay QR Code](https://docs.fabrick.com/en/assets/images/applepay-checkout-page-03-14b9796b29d73b30c586971bf8c115c7.png) ### Additional configuration for Web Component and Lightbox With these integrations Apple Pay runs directly on the merchant's domain. **Domain verification** is required to authorise the execution of the Apple JavaScript and the generation of the payment token. To complete the verification, the certification file provided by Fabrick must be publicly hosted on the domain on which the Web Component or the Lightbox is integrated, at the following path: `https://your-domain.com/.well-known/apple-developer-merchantid-domain-association` > **Publishing domain** > > The file must be publicly reachable on the **actual integration domain**, with no authentication and no redirects. 1. Download the Fabrick certification file from: [https://web.fabrick.com/.well-known/apple-developer-merchantid-domain-association](https://web.fabrick.com/.well-known/apple-developer-merchantid-domain-association) 2. Name it exactly `apple-developer-merchantid-domain-association`, **with no extension** (`.txt`, `.cer`, etc.) 3. Upload it to your server in the `/.well-known/` folder 4. Check that the file is publicly accessible at the URL above > **Activation complete** > > Once the file is published, **provide the domain** to your sales representative or to [support](https://landing.fabrick.com/fabrick-dashboard-support) to complete the configuration. --- ## API integration ### Activation requirements To use the API integration for Apple Pay you need: - **Apple Developer Account**: access to *Certificates, Identifiers & Profiles* to manage the certificates required for the integration. - **Payment Processing Certificate**: [certificate associated with the Merchant ID](https://developer.apple.com/help/account/capabilities/configure-apple-pay), used by Apple to encrypt the payment data. It must be generated from the CSR provided by Fabrick and uploaded to the Gestpay dashboard. - **Merchant Identity Certificate**: [certificate used to authenticate communication](https://developer.apple.com/help/account/capabilities/configure-apple-pay-on-the-web) with the Apple servers during the merchant validation phase. Required for integration through the Apple Pay JS API *(web integration only)*. > **Certificate expiry and renewal** > > Both certificates are [valid for **25 months**](https://developer.apple.com/documentation/applepayontheweb/maintaining-your-environment). Apple sends reminder emails before they expire. If they are not renewed: > > - **Payment Processing Certificate** expired → Apple can no longer encrypt the payment data and **all Apple Pay transactions stop**. To renew it: download a new CSR from the Gestpay dashboard, generate a new certificate on the Apple Developer portal and upload it to Fabrick. > - **Merchant Identity Certificate** expired → merchant validation fails and **Apple Pay web payments stop**. To renew it: generate a new certificate from the Apple Developer portal. --- ### Configuring the Apple certificates #### Generating the CSR The **CSR (Certificate Signing Request)** can be downloaded from the Gestpay dashboard under **Configurazione → Sistemi di pagamento → Apple Pay** and is needed to generate the **Payment Processing Certificate** from the Apple portal. This certificate allows Fabrick to handle the Payment Token Packages securely on the merchant's behalf. ![Downloading the Apple Pay CSR from the Gestpay dashboard](https://docs.fabrick.com/en/assets/images/applepay-config-gestpay-01-bb6ece0e32d125c0ba47b4008626e716.png) Once the CSR is downloaded, access the Apple Pay Member Center to generate the certificate and then upload it to the Gestpay dashboard. > **CSR availability** > > The CSR is not available immediately after activation: the system may take up to 2 hours to generate it. If you download it before it is ready, an error is returned. > > ![Download error for a CSR not yet available](https://docs.fabrick.com/en/assets/images/applepay-config-gestpay-03-386c9729cfd12dd96e7cb30d8b506b2c.png) #### Uploading the certificate Once the Apple certificate has been generated, upload it to the Gestpay dashboard through the **+ Aggiungi un Payment Processing Certificate** section. ![Uploading the Payment Processing Certificate to the Gestpay dashboard](https://docs.fabrick.com/en/assets/images/applepay-config-gestpay-02-904179b586f1fab8ffa6afe2e9353c51.png) --- ### Requesting a payment with Apple Pay #### 1. Obtaining the Payment Token Package The Payment Token Package ([Apple reference format](https://developer.apple.com/documentation/PassKit/payment-token-format-reference)) is generated by the buyer's device through the Apple APIs. To obtain it you need to integrate Apple Pay into your platform, following the [Apple Pay brand guidelines](https://developer.apple.com/design/human-interface-guidelines/apple-pay). Apple provides two distinct SDKs depending on the integration context: - **iOS app (native)** → PassKit framework — [PassKit documentation](https://developer.apple.com/documentation/passkit/apple-pay) - **Website** → Apple Pay JS API — [Apple Pay on the Web documentation](https://developer.apple.com/documentation/apple_pay_on_the_web) · [Interactive demo](https://applepaydemo.apple.com/apple-pay-js-api) Once the token has been obtained, the flow for sending it to Fabrick is the same in both cases. > **SDKs are not interchangeable** > > PassKit is exclusive to native iOS apps, Apple Pay JS to the web. To support both contexts you need to implement them separately. > > Starting with iOS 18, [Apple Pay on the Web is no longer limited to Safari](https://support.apple.com/guide/safari/apple-pay-in-third-party-browsers-ibrw9b779bd3/mac): on non-WebKit browsers (e.g. Chrome, Edge, including on Windows PCs) the payment is completed by scanning a code with an iPhone or iPad. The feature is only available at participating merchants and not in all markets. | Key | Type | Description | | ------------------------ | ------ | ----------------------------------------------------------- | | `applePayPKPaymentToken` | string | Payment Token Package serialised as a UTF-8 JSON **string** | | `PKPaymentToken` | object | Payment Token Package as a structured JSON **object** | The structure of the package is the same in both forms. The schema of the package is as follows: **Payment Token Package (schema)** ```json { "paymentData": { "data": "", "signature": "", "header": { "publicKeyHash": "", "ephemeralPublicKey": "", "transactionId": "" }, "version": "EC_v1" }, "transactionIdentifier": "", "paymentMethod": { "network": "Visa", "type": "debit", "displayName": "Visa 0492" } } ``` > **Which field to use** > > Send the package in the field matching the form in which the token is available in your code: `PKPaymentToken` if it is a JSON **object**, `applePayPKPaymentToken` if it is a serialised **string** (the whole object enclosed in quotes, with the inner quotes escaped). #### 2. Sending the payment request to Fabrick Once you have obtained the Payment Token Package, the payment is handled in two consecutive steps: `payment/create` to initialise the transaction and `payment/submit` to send the Apple Pay token. > **warning** > > The **amount** and **currency** values passed to `payment/create` must match exactly those used in the Apple Pay request generated through the Apple SDKs. ##### Step 1 — Creating the transaction **Request** ```http POST /api/v1/payment/create Host (sandbox): sandbox.gestpay.net Host (production): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "amount": "100", "currency": "EUR", "shopTransactionID": "FBK_OrderID" } ``` **Response** ```json { "error": { "code": "0", "description": "request correctly processed" }, "payload": { "paymentToken": "f0419188-8a78-4918-913c-a491e4e78084", "paymentID": "1881129911957", "userRedirect": null, "qrCode": null } } ``` ##### Step 2 — Sending the token and processing Send a request to `payment/submit` with the Apple Pay token: - **`PaymentToken`** header: populate it with the `paymentToken` received from [Step 1](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/alternative-payments/apple-pay/#step-1--creating-the-transaction) - Body: place the full Apple Pay token in `paymentTypeDetails.applePay.PKPaymentToken` (JSON object) **or** in `paymentTypeDetails.applePay.applePayPKPaymentToken` (serialised string), depending on the form in which the token is available > **SCA authentication** > > Apple Pay includes built-in authentication (Face ID / Touch ID) which, as [Apple](https://developer.apple.com/support/sca/) states, **satisfies the SCA requirements**: in most cases the transaction does not require further authentication by the bank. > > When the issuer still requires additional authentication, SCA must be handled: in this case the `payment/submit` response carries the authentication URL in `userRedirect.href`, to which the buyer must be redirected to complete the payment. The integration must therefore always handle a possible redirect. **Request** ```http POST /api/v1/payment/submit Host (sandbox): sandbox.gestpay.net Host (production): ecomms2s.sella.it PaymentToken: f0419188-8a78-4918-913c-a491e4e78084 Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "paymentType": "APPLEPAY", "paymentTypeDetails": { "applePay": { "PKPaymentToken": { "paymentData": { "data": "Q0tfx6QzXdx...", "signature": "MIAGCSqGSIb3DQEHAq...", "header": { "publicKeyHash": "b9OHKov7pD...", "ephemeralPublicKey": "MFkwE...", "transactionId": "df9ea7239074..." }, "version": "EC_v1" }, "paymentMethod": { "displayName": "Visa 0121", "network": "Visa", "type": "credit" }, "transactionIdentifier": "DF9EA72390..." } } } } ``` As an alternative to the object, the same package can be sent as a **serialised string** by populating `applePayPKPaymentToken` instead of `PKPaymentToken` (the response is the same): ```json { "shopLogin": "GESPAY12345", "paymentType": "APPLEPAY", "paymentTypeDetails": { "applePay": { "applePayPKPaymentToken": "{\"paymentData\":{\"data\":\"Q0tfx6QzXdx...\",\"signature\":\"MIAGCSqGSIb3DQEHAq...\",\"header\":{\"publicKeyHash\":\"b9OHKov7pD...\",\"ephemeralPublicKey\":\"MFkwE...\",\"transactionId\":\"df9ea7239074...\"},\"version\":\"EC_v1\"},\"transactionIdentifier\":\"DF9EA72390...\",\"paymentMethod\":{\"displayName\":\"Visa 0121\",\"network\":\"Visa\",\"type\":\"credit\"}}" } } } ``` **Response** ```json { "error": { "code": "0", "description": "request correctly processed" }, "payload": { "transactionType": "submit", "transactionResult": "OK", "transactionErrorCode": "0", "transactionErrorDescription": "Transaction correctly processed", "bankTransactionID": "2527", "shopTransactionID": "FBK_OrderID", "shopTransactionID_2": "", "authorizationCode": "177260", "paymentID": "1881129911957", "currency": "EUR", "country": "", "company": "APPLEPAY - VISA", "tdLevel": "HALF", "buyer": { "name": "", "email": "" }, "risk": { "riskResponseCode": "", "riskResponseDescription": "" }, "customInfo": {}, "alertCode": "", "alertDescription": "", "cvvPresent": "N", "maskedPAN": "", "paymentMethod": "", "productType": "", "token": "", "tokenExpiryMonth": "", "tokenExpiryYear": "", "userRedirect": { "href": "https://sandbox.gestpay.net/pagam/AxerveThankYou.aspx" } } } ``` The response returns the outcome of the transaction with `transactionResult: "OK"` if the payment was completed successfully. At the same time, the system sends a server-to-server (S2S) notification with the outcome of the transaction. --- ## Additional payment method features You can enable additional features on the transaction by amending the `payment/create` call to include the specific services, such as [Fabrick Guaranteed Payments](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/features/fraud-prevention/fabrick-guaranteed-payments/). The services configured are applied automatically to the transaction when the buyer selects Apple Pay. ### Separated and unified capture Apple Pay is handled as a card: the transaction handling mode, **unified** or **separated**, is the one configured for cards and requires no dedicated setting. To check or change the configuration: 1. Log in to the Dashboard and go to **Settings → Access the configurations** ![Accessing the configurations from the Dashboard](https://docs.fabrick.com/en/assets/images/dashboard-access-configurations-f4782eb17db7b8fb6f23649ba8e3e5d7.png) 2. Once redirected to the back office, go to **Configurations → Environment** and click **MOTO**: a side panel opens with the list of active payment methods 3. Find the **cards** row and select the required mode between **Unified** and **Separated** > **Configuration shared with cards** > > The mode set for cards applies to all card payments, including those made with Apple Pay and Google Pay: changing it for the wallet means changing it for cards too. > **MOTO** > > For more details on how the two modes work, see the [separated and unified capture](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/introduction/getting-started/#moto) section. ### Tokenization The payment method used with Apple Pay can be **tokenized**: Fabrick returns a token representing the card the buyer chose in their Wallet, which can be reused for subsequent charges without asking for the payment details again. Tokenization is requested in the `payment/create` call, by populating the `requestToken` field with `MASKEDPAN`. **Hosted integration** The `payment/create` call is enough: Fabrick handles the Apple Pay button, the generation of the Payment Token Package and the return of the token. **Request** ```http POST /api/v1/payment/create Host (sandbox): sandbox.gestpay.net Host (production): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "amount": "100", "currency": "EUR", "shopTransactionID": "FBK_OrderID", "paymentChannel": { "channelType": ["LINK"] }, // Pay By Link only "requestToken": "MASKEDPAN" } ``` > **Limiting the page to cards and wallets** > > By populating `paymentType` with `["CREDITCARD"]` the payment page displays the card and the wallets enabled on the shopLogin, Apple Pay among them. The request does not change according to the method the buyer chooses, and the token returned corresponds to the method used. **API integration** The `requestToken` field goes in the `payment/create` call. In the `payment/submit` call, which carries the Payment Token Package, the field **must not be repeated**. **Request** ```http POST /api/v1/payment/create Host (sandbox): sandbox.gestpay.net Host (production): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "amount": "100", "currency": "EUR", "shopTransactionID": "FBK_OrderID", "requestToken": "MASKEDPAN" } ``` The `payment/submit` call remains the one described in [Step 2](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/alternative-payments/apple-pay/#step-2--sending-the-token-and-processing). The token is available in the `payment/detail` response, in the `payload.token` field. For more information about the token, you can read the `payload.tokenDetails` object. > **Token management** > > For reading the token data, amending it and deleting it, see [Reading token data](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/features/token/#reading-token-data). ### Recurring payments Apple Pay can be used as the payment method of a **recurring series**. The buyer authorises the first payment of the series (**First**, CIT) with their own authentication, while the subsequent payments (**Next**, MIT) are carried out by the merchant in their absence, using the token obtained during the First. | Transaction | Available integrations | Data to send | | --------------- | ------------------------------- | -------------------------------------------------------------------- | | **First (CIT)** | Hosted integrations or API Only | Apple Pay payload, as an object or as a string, or an existing token | | **Next (MIT)** | API | Token generated or used in the First | > **Wallets are handled as cards** > > In Next transactions the token must always be sent in the `paymentTypeDetails.creditcard.token` field, even when the First was paid with Apple Pay. The Next flow is therefore the same as the card one. For the full flow, the mandatory fields of the First, the data to save and how to handle the `8026` soft decline, see [Recurring payments with cards and wallets](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/features/recurring-payments/). --- ## Support **Fabrick** - **Status page**: [https://status.fabrick.com/](https://status.fabrick.com/) - **Support**: [https://landing.fabrick.com/fabrick-dashboard-support](https://landing.fabrick.com/fabrick-dashboard-support) **Apple** - **Support**: [https://developer.apple.com/contact/apple-pay/](https://developer.apple.com/contact/apple-pay/)