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.

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 and for web integrations through Apple Pay JS.
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).
Recurring payments: Apple Pay can be used as the payment method of a recurring series (see 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).
Fabrick Guaranteed Payments: fraud prevention service supporting the merchant (find out more).
Simplified reconciliation: payment management through dedicated reports (find out more).
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

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

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 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 and an Apple device configured in sandbox mode with a test card added to the Wallet.

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

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

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

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.

Download the Fabrick certification file from: https://web.fabrick.com/.well-known/apple-developer-merchantid-domain-association
Name it exactly apple-developer-merchantid-domain-association, with no extension (.txt, .cer, etc.)
Upload it to your server in the /.well-known/ folder
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 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, 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 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. 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

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

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

Requesting a payment with Apple Pay

1. Obtaining the Payment Token Package

The Payment Token Package (Apple reference format) 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.

Apple provides two distinct SDKs depending on the integration context:

iOS app (native) → PassKit framework — PassKit documentation
Website → Apple Pay JS API — Apple Pay on the Web documentation · Interactive demo

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: 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)
{
  "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

POST /api/v1/payment/create
Host (sandbox): sandbox.gestpay.net
Host (production): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/json

{
  "shopLogin": "GESPAY12345",
  "amount": "100",
  "currency": "EUR",
  "shopTransactionID": "FBK_OrderID"
}

Response

{
  "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
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 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

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

{
  "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):

{
  "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

{
  "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. 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:

Log in to the Dashboard and go to Settings → Access the configurations
Once redirected to the back office, go to Configurations → Environment and click MOTO: a side panel opens with the list of active payment methods
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 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
API 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

POST /api/v1/payment/create
Host (sandbox): sandbox.gestpay.net
Host (production): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/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.

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

POST /api/v1/payment/create
Host (sandbox): sandbox.gestpay.net
Host (production): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/json

{
    "shopLogin": "GESPAY12345",
    "amount": "100",
    "currency": "EUR",
    "shopTransactionID": "FBK_OrderID",
    "requestToken": "MASKEDPAN"
}

The payment/submit call remains the one described in Step 2.

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.

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.

Support

Fabrick

Status page: https://status.fabrick.com/
Support: https://landing.fabrick.com/fabrick-dashboard-support

Apple

Support: https://developer.apple.com/contact/apple-pay/

Apple Pay

Why choose Apple Pay​

Services and features available through the Fabrick integration​

Apple Pay on Fabrick Payment Orchestra: activation and integration types​

Activation request​

Integration types​

Supported integrations

Supported integrations

Hosted integration​

Additional configuration for Web Component and Lightbox​

API integration​

Activation requirements​

Configuring the Apple certificates​

Generating the CSR​

Uploading the certificate​

Requesting a payment with Apple Pay​

1. Obtaining the Payment Token Package​

2. Sending the payment request to Fabrick​

Step 1 — Creating the transaction​

Step 2 — Sending the token and processing​

Additional payment method features​

Separated and unified capture​

Tokenization​

Recurring payments​

Support​

Why choose Apple Pay

Services and features available through the Fabrick integration

Apple Pay on Fabrick Payment Orchestra: activation and integration types

Activation request

Integration types

Hosted integration

Additional configuration for Web Component and Lightbox

API integration

Activation requirements

Configuring the Apple certificates

Generating the CSR

Uploading the certificate

Requesting a payment with Apple Pay

1. Obtaining the Payment Token Package

2. Sending the payment request to Fabrick

Step 1 — Creating the transaction

Step 2 — Sending the token and processing

Additional payment method features

Separated and unified capture

Tokenization

Recurring payments

Support