Passa al contenuto principale

Apple Pay

Perché scegliere Apple Pay​

Apple Pay è il wallet digitale sviluppato da Apple che permette di effettuare pagamenti in modo semplice, veloce e sicuro tramite iPhone, Apple Watch, iPad e Mac.

Integrarlo nell'ecommerce amplia le modalità di pagamento disponibili e migliora l'esperienza utente grazie a un checkout rapido e senza frizioni. Elimina la necessità di inserire manualmente i dati della carta e, grazie a Face ID e Touch ID, i clienti autorizzano i pagamenti in modo immediato con un semplice gesto.

Approfondimento

Per ulteriori informazioni consulta la documentazione ufficiale Apple

Servizi e funzionalità disponibili tramite integrazione Fabrick​

L'integrazione di Apple Pay con Fabrick Payment Orchestra mette a disposizione un ecosistema completo di funzionalità per semplificare la gestione delle transazioni e migliorare l'esperienza sia per il venditore che per il cliente.

  • Compatibile con app e siti web: supporto sia per app iOS tramite PassKit che per integrazioni web tramite Apple Pay JS.
  • Certificati dedicati: caricamento dei Payment Processing Certificate direttamente dalla dashboard Gestpay per la gestione dell'integrazione diretta.
  • Gestione Payment Token: Fabrick gestisce autonomamente il token di pagamento presentando Apple Pay sulla propria pagina, senza sviluppi aggiuntivi lato merchant.
  • SCA nativa: l'autenticazione biometrica di Apple Pay (Face ID / Touch ID) soddisfa i requisiti SCA, riducendo nella maggior parte dei casi la necessità di un'autenticazione aggiuntiva. (scopri di più).
  • Fabrick Guaranteed Payments: servizio di prevenzione frodi a supporto dell'esercente (scopri di più).
  • Riconciliazione semplificata: gestione dei pagamenti tramite report dedicati (scopri di più).
  • Gestione avanzata delle transazioni: supporto a catture e storni parziali o multipli per una gestione flessibile dei pagamenti.
  • Supporto multivaluta: Apple Pay accetta i codici valuta dello standard ISO 4217; le valute effettivamente processabili dipendono dalla configurazione del tuo profilo Fabrick.
  • Supporto circuiti internazionali: Apple Pay tramite Fabrick supporta Visa, Mastercard e American Express.

Apple Pay su Fabrick Payment Orchestra: attivazione e modalità di integrazione​

Richiesta di attivazione​

Puoi richiedere l'attivazione di Apple Pay tramite Fabrick:

  • Contattando il tuo referente commerciale
  • Contattando l'assistenza al seguente link

Una volta ricevuta la conferma, puoi verificare l'attivazione dalla dashboard:

  1. Accedi alla Dashboard Fabrick
  2. Dal menu laterale, seleziona Workspace → Negozi → [Seleziona negozio] → Configurazioni
  3. Nella lista dei metodi di pagamento, individua Apple Pay e verifica che lo stato risulti Attivo

Apple Pay

Attivazione completata

Da questo momento, il tuo e-commerce è pronto per accettare pagamenti Apple Pay tramite Fabrick Payment Orchestra.

Tipologie di integrazione​

Fabrick offre due modalità di integrazione per utilizzare Apple Pay:

  • Integrazione hosted

    Integrazioni supportate

    ✓HPPO
    ✓Pay By Link
    ✓Web Component
    ✓Lightbox

    Apple Pay viene mostrato direttamente nella pagina di pagamento. Fabrick gestisce autonomamente pulsante, token e processamento della transazione, con un passaggio di configurazione aggiuntivo per Web Component e Lightbox.

  • Integrazione tramite API

    Integrazioni supportate

    ✓API Only

    In questa modalità Apple Pay viene integrato direttamente sul sito o sull'app. Richiede il caricamento dei certificati Apple nella dashboard Gestpay, l'implementazione del pulsante di pagamento, la generazione del token e il relativo invio a Fabrick per l'elaborazione.

Testare Apple Pay in ambiente sandbox

Per effettuare i test è necessario disporre di un account Apple developer e un dispositivo Apple configurato in modalità sandbox con una carta di test aggiunta al Wallet.

Integrazione hosted​

Apple Pay viene mostrato direttamente nella pagina di pagamento. Fabrick gestisce autonomamente l'esecuzione degli script Apple e la generazione del token di pagamento.

Apple Pay

Il pagamento è disponibile su tutti i browser, anche da dispositivi non Apple. In questo caso viene mostrato un QR Code che consente di completare il pagamento tramite un dispositivo Apple esterno: dopo la scansione, il flusso viene avviato sul dispositivo e la transazione processata da Fabrick.

Apple Pay

Se il QR Code scade, è possibile generarne uno nuovo per la stessa transazione cliccando su Ricevi nuovo codice.

Apple Pay

Configurazione aggiuntiva per Web Component e Lightbox​

Per queste integrazioni, Apple Pay viene eseguito direttamente sul dominio dell'esercente. È richiesta la verifica del dominio per autorizzare l'esecuzione del JavaScript Apple e la generazione del token di pagamento.

Per completare la verifica, il file di certificazione fornito da Fabrick deve essere ospitato pubblicamente sul dominio su cui è integrato il Web Component o la Lightbox, al seguente percorso:

https://tuo-dominio.com/.well-known/apple-developer-merchantid-domain-association

Dominio di pubblicazione

Il file deve essere raggiungibile pubblicamente sul dominio effettivo di integrazione.

  1. Scarica il file di certificazione Fabrick da: https://web.fabrick.com/.well-known/apple-developer-merchantid-domain-association
  2. Rinominalo esattamente apple-developer-merchantid-domain-association — senza alcuna estensione (.txt, .cer, ecc.)
  3. Caricalo sul tuo server nella cartella /.well-known/
  4. Verifica che il file sia accessibile pubblicamente all'URL indicato sopra
Attivazione completata

Una volta pubblicato il file, comunica il dominio al tuo referente commerciale o all'assistenza per completare la configurazione.

Integrazione tramite API​

Requisiti per l'attivazione​

Per utilizzare l'Integrazione tramite API con Apple Pay tramite Fabrick sono necessari:

  • Apple Developer Account: accesso a Certificates, Identifiers & Profiles per gestire i certificati richiesti per l'integrazione.

  • Payment Processing Certificate: certificato associato al Merchant ID, utilizzato da Apple per cifrare i dati di pagamento. Deve essere generato a partire dal CSR fornito da Fabrick e caricato nella dashboard Gestpay.

  • Merchant Identity Certificate: certificato per autenticare la comunicazione con i server Apple durante la fase di merchant validation. Richiesto per l'integrazione via Apple Pay JS API (solo per integrazione web).

Scadenza e rinnovo dei certificati

Entrambi i certificati hanno una validità di 25 mesi. Apple invia notifiche email di promemoria prima della scadenza. In assenza di rinnovo:

  • Payment Processing Certificate scaduto → Apple non può più cifrare i dati di pagamento e tutte le transazioni Apple Pay vengono interrotte. Per rinnovarlo: scarica un nuovo CSR dalla dashboard Gestpay, genera un nuovo certificato sul portale Apple Developer e caricalo su Fabrick.
  • Merchant Identity Certificate scaduto → la merchant validation fallisce e i pagamenti Apple Pay via web vengono interrotti. Per rinnovarlo: genera un nuovo certificato dal portale Apple Developer.

Configurazione dei certificati Apple​

Generare il CSR​

Il CSR (Certificate Signing Request) è scaricabile dalla dashboard Gestpay in Configurazione → Sistemi di pagamento → Apple Pay ed è necessario per generare il Payment Processing Certificate dal portale Apple. Questo certificato permette a Fabrick di gestire in sicurezza i Payment Token Package per conto dell'esercente.

Apple Pay

Una volta scaricato il CSR, accedi all'Apple Pay Member Center per generare il certificato e caricarlo successivamente nella dashboard Gestpay.

Disponibilità del CSR

Il CSR non è immediatamente disponibile dopo l'attivazione: il sistema può impiegare fino a 2 ore per generarlo. Se scaricato prima che sia pronto, verrà restituito un errore.

Apple Pay

Caricamento del certificato​

Dopo aver generato il certificato Apple, caricalo nella dashboard Gestpay tramite la sezione + Aggiungi un Payment Processing Certificate.

Apple Pay

Richiedere un pagamento con Apple Pay​

1. Ottenimento del Payment Token Package​

Il Payment Token Package (formato di riferimento Apple) viene generato dal dispositivo del cliente tramite le API Apple. Per ottenerlo è necessario integrare Apple Pay sulla propria piattaforma rispettando le linee guida di brand Apple Pay.

Apple mette a disposizione due SDK distinti in base al contesto di integrazione:

Una volta ottenuto il token, il flusso di invio verso Fabrick è identico in entrambi i casi.

SDK non intercambiabili

PassKit è esclusivo per le app native iOS, Apple Pay JS per il web. Per supportare entrambi i contesti è necessario implementarli separatamente.

A partire da iOS 18, Apple Pay on the Web non è più limitato a Safari: sui browser non basati su WebKit (es. Chrome, Edge, anche su PC Windows) il pagamento viene completato scansionando un codice con iPhone o iPad. La funzionalità è disponibile solo presso merchant partecipanti e non in tutti i mercati.

KeyTipoDescrizione
applePayPKPaymentTokenstringPayment Token Package serializzato come stringa JSON UTF-8
PKPaymentTokenobjectPayment Token Package come oggetto JSON strutturato

La struttura del package è la stessa nelle due forme. Lo schema del package è il seguente:

Payment Token Package (schema)
{
  "paymentData": {
    "data": "",
    "signature": "",
    "header": {
      "publicKeyHash": "",
      "ephemeralPublicKey": "",
      "transactionId": ""
    },
    "version": "EC_v1"
  },
  "transactionIdentifier": "",
  "paymentMethod": {
    "network": "Visa",
    "type": "debit",
    "displayName": "Visa 0492"
  }
}
Quale campo usare

Invia il package nel campo corrispondente alla forma in cui disponi del token nel tuo codice: PKPaymentToken se è un oggetto JSON, applePayPKPaymentToken se è una stringa serializzata (l'intero oggetto racchiuso tra virgolette, con escape delle virgolette interne).

2. Invio della richiesta di pagamento a Fabrick​

Una volta ottenuto il Payment Token Package, il pagamento viene gestito in due step consecutivi: payment/create per inizializzare la transazione e payment/submit per inviare il token Apple Pay.

warning

I valori di importo e valuta passati a payment/create devono coincidere esattamente con quelli utilizzati nella richiesta Apple Pay generata tramite gli SDK Apple.

Step 1 — Creazione della transazione​

Request

POST /api/v1/payment/create
Host (sandbox): sandbox.gestpay.net
Host (produzione): 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 — Invio del token e processamento​

Inviare una richiesta a payment/submit con il token Apple Pay:

  • Header PaymentToken: valorizzare con il paymentToken ricevuto dallo Step 1
  • Body: inserire il token Apple Pay completo in paymentTypeDetails.applePay.PKPaymentToken (oggetto JSON) oppure in paymentTypeDetails.applePay.applePayPKPaymentToken (stringa serializzata), in base alla forma in cui disponi del token
Autenticazione SCA

Apple Pay include un'autenticazione integrata (Face ID / Touch ID) che, come riporta Apple, soddisfa i requisiti SCA: nella maggior parte dei casi la transazione non richiede un'ulteriore autenticazione da parte della banca.

Quando l'emittente richiede comunque un'autenticazione aggiuntiva, è necessario gestire la SCA: in questo caso la response di payment/submit veicola l'URL di autenticazione in userRedirect.href, a cui il buyer deve essere reindirizzato per completare il pagamento. L'integrazione deve quindi gestire sempre l'eventuale redirect.

Request

POST /api/v1/payment/submit
Host (sandbox): sandbox.gestpay.net
Host (produzione): 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..."
      }
    }
  }
}

In alternativa all'oggetto, lo stesso package può essere inviato come stringa serializzata valorizzando applePayPKPaymentToken al posto di PKPaymentToken (la response è identica):

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

La response restituisce l'esito della transazione con transactionResult: "OK" se il pagamento è completato con successo. Contestualmente, il sistema invia una notifica server to server (S2S) con l'esito della transazione.

Funzionalità aggiuntive del metodo di pagamento​

Puoi abilitare funzionalità aggiuntive sulla transazione modificando la chiamata payment/create per includere i servizi specifici, come Fabrick Guaranteed Payment. I servizi configurati verranno applicati automaticamente alla transazione quando il cliente seleziona Apple Pay.

Assistenza​

Fabrick

Apple