Skip to main content

Apple Pay

Why choose Apple Pay​

Apple Pay is the digital wallet developed by Apple that allows customers to pay simply, quickly and securely via iPhone, Apple Watch, iPad and Mac.

Integrating it into your e-commerce expands the available payment methods and improves the user experience thanks to a fast, frictionless checkout. It removes the need to manually enter card details and, thanks to Face ID and Touch ID, customers authorize payments instantly with a simple gesture.

Learn more

For further information, see the official Apple documentation

Services and features available through the Fabrick integration​

Integrating Apple Pay with Fabrick Payment Orchestra provides a complete ecosystem of features to simplify transaction management and improve the experience for both the merchant and the customer.

  • Compatible with apps and websites: support for both iOS apps via PassKit and web integrations via Apple Pay JS.
  • Dedicated certificates: upload of Payment Processing Certificates directly from the Gestpay dashboard to manage the direct integration.
  • Payment Token management: Fabrick autonomously handles the payment token by presenting Apple Pay on its own page, with no additional development required on the merchant side.
  • Native SCA: Apple Pay biometric authentication (Face ID / Touch ID) satisfies SCA requirements, reducing in most cases the need for additional authentication. (learn more).
  • Fabrick Guaranteed Payments: fraud prevention service supporting the merchant (learn more).
  • Simplified reconciliation: payment management through dedicated reports (learn more).
  • Advanced transaction management: support for partial or multiple captures and refunds for flexible payment handling.
  • Multi-currency support: Apple Pay accepts ISO 4217 currency codes; the currencies that can actually be processed depend on your Fabrick profile configuration.
  • International card scheme support: Apple Pay via Fabrick supports Visa, Mastercard and American Express.

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

Activation request​

You can request Apple Pay activation with Fabrick by:

  • Contacting your sales representative
  • Contacting support at the following link

Once you receive confirmation, you can verify the activation from the dashboard:

  1. Log in to the Fabrick Dashboard
  2. From the side menu, select Workspace → Stores → [Select store] → Configurations
  3. In the list of payment methods, locate Apple Pay and check that its status is Active

Apple Pay

Activation completed

From this moment on, your e-commerce is ready to accept Apple Pay payments through Fabrick Payment Orchestra.

Integration types​

Fabrick offers two integration options for Apple Pay:

  • Hosted integration

    Supported integrations

    ✓HPPO
    ✓Pay By Link
    ✓Web Component
    ✓Lightbox

    Apple Pay is displayed directly on the payment page. Fabrick autonomously manages the button, the token and the transaction processing, with an additional configuration step required for Web Component and Lightbox.

  • API integration

    Supported integrations

    ✓API Only

    In this mode, Apple Pay is integrated directly into your 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 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 autonomously manages the execution of the Apple scripts and the generation of the payment token.

Apple Pay

Payment is available on all browsers, including non-Apple devices. In this case a QR Code is displayed, allowing the payment to be completed through an external Apple device: after scanning, the flow starts on the device and the transaction is processed by Fabrick.

Apple Pay

If the QR Code expires, you can generate a new one for the same transaction by clicking Receive new code.

Apple Pay

Additional configuration for Web Component and Lightbox​

For these integrations, Apple Pay runs directly on the merchant's domain. Domain verification is required to authorize 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 where 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.

  1. Download the Fabrick certification file from: https://web.fabrick.com/.well-known/apple-developer-merchantid-domain-association
  2. Rename it exactly apple-developer-merchantid-domain-association — without any extension (.txt, .cer, etc.)
  3. Upload it to your server in the /.well-known/ folder
  4. Verify that the file is publicly accessible at the URL indicated above
Activation completed

Once the file is published, communicate the domain to your sales representative or to support to complete the configuration.

API integration​

Activation requirements​

To use the API integration with Apple Pay via Fabrick 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 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 the communication with Apple servers during the merchant validation phase. Required for the Apple Pay JS API integration (web integration only).

Certificate expiration and renewal

Both certificates are valid for 25 months. Apple sends email reminders before expiration. If not renewed:

  • Payment Processing Certificate expired → Apple can no longer encrypt payment data and all Apple Pay transactions are interrupted. 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 are interrupted. 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 Configuration → Payment systems → Apple Pay and is required to generate the Payment Processing Certificate from the Apple portal. This certificate allows Fabrick to securely handle Payment Token Packages on behalf of the merchant.

Apple Pay

Once the CSR has been 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 immediately available after activation: the system can take up to 2 hours to generate it. If downloaded before it is ready, an error will be returned.

Apple Pay

Uploading the certificate​

After generating the Apple certificate, upload it to the Gestpay dashboard via the + Add a Payment Processing Certificate section.

Apple Pay

Requesting a payment with Apple Pay​

1. Obtaining the Payment Token Package​

The Payment Token Package (Apple format reference) is generated by the customer's device through the Apple APIs. To obtain it, you need to integrate Apple Pay into your platform in compliance with the Apple Pay brand guidelines.

Apple provides two distinct SDKs depending on the integration context:

Once the token has been obtained, the submission flow towards Fabrick is identical in both cases.

SDKs are not interchangeable

PassKit is exclusive to native iOS apps, Apple Pay JS to the web. To support both contexts, they must be implemented separately.

Starting from 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. This feature is available only with participating merchants and not in all markets.

KeyTypeDescription
applePayPKPaymentTokenstringPayment Token Package serialized as a UTF-8 JSON string
PKPaymentTokenobjectPayment Token Package as a structured JSON object

The package structure is the same in both forms. The package schema 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 exists in your code: PKPaymentToken if it is a JSON object, applePayPKPaymentToken if it is a serialized string (the whole object enclosed in quotes, with inner quotes escaped).

2. Sending the payment request to Fabrick​

Once the Payment Token Package has been obtained, the payment is handled in two consecutive steps: payment/create to initialize the transaction and payment/submit to send the Apple Pay token.

warning

The amount and currency values passed to payment/create must exactly match 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: set it to the paymentToken received in Step 1
  • Body: place the full Apple Pay token in paymentTypeDetails.applePay.PKPaymentToken (JSON object) or in paymentTypeDetails.applePay.applePayPKPaymentToken (serialized string), depending on the form in which the token exists in your code
SCA authentication

Apple Pay includes built-in authentication (Face ID / Touch ID) which, as stated by Apple, satisfies SCA requirements: in most cases the transaction does not require additional authentication from the bank.

When the issuer nevertheless 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 the potential 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 serialized string by populating applePayPKPaymentToken instead of PKPaymentToken (the response is identical):

{
  "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": "Transazione correttamente effettuata",
    "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 transaction outcome with transactionResult: "OK" if the payment is completed successfully. At the same time, the system sends a server-to-server (S2S) notification with the transaction outcome.

Additional payment method features​

You can enable additional features on the transaction by modifying the payment/create call to include specific services, such as Fabrick Guaranteed Payment. The configured services will be automatically applied to the transaction when the customer selects Apple Pay.

Support​

Fabrick

Apple