Passa al contenuto principale

Apple Pay

Visualizza come Markdown

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.
  • Tokenizzazione: il metodo di pagamento può essere tokenizzato per riutilizzarlo negli addebiti successivi (vedi Tokenizzazione).
  • Pagamenti ricorrenti: Apple Pay può essere utilizzato come metodo di pagamento di una serie ricorrente (vedi Pagamenti ricorrenti).
  • 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​

Per iniziare ad accettare pagamenti con Apple Pay, puoi richiedere l'attivazione:

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

Una volta completate le procedure necessarie:

  • Fabrick abilita Apple Pay sul negozio e informa l'esercente.
  • È possibile verificare l'attivazione del metodo di pagamento all'interno della Dashboard, al percorso Workspace → Negozi → [Seleziona negozio] → Configurazioni

Attivazione di Apple Pay in Dashboard

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

    ✓Checkout Page
    ✓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 ulteriore passaggio di configurazione 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 nella pagina di pagamento Fabrick

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.

QR Code Apple Pay per il pagamento da dispositivo non Apple

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

Rigenerazione del QR Code Apple Pay scaduto

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, senza autenticazione e senza redirect.

  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 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.

Download del CSR Apple Pay dalla dashboard Gestpay

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.

Errore di download del CSR non ancora disponibile

Caricamento del certificato​

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

Caricamento del Payment Processing Certificate nella dashboard Gestpay

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

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 Payments. I servizi configurati verranno applicati automaticamente alla transazione quando il buyer seleziona Apple Pay.

Separazione tra autorizzazione e cattura​

Apple Pay è gestito come una carta: la modalità di gestione delle transazioni, contestuale o separata, è quella configurata per le carte e non richiede un'impostazione dedicata.

Per verificare o modificare la configurazione:

  1. Accedi alla Dashboard e vai su Impostazioni → Accedi alle configurazioni Accesso alle configurazioni dalla Dashboard

  2. Una volta reindirizzato sul backoffice, vai su Configurazioni → Ambiente e clicca su MOTO: si apre un pannello laterale con l'elenco dei metodi di pagamento attivi

  3. Individua la riga delle carte e seleziona la modalità desiderata tra Contestuale e Separata

Configurazione condivisa con le carte

La modalità impostata per le carte vale per tutti i pagamenti con carta, inclusi quelli effettuati con Apple Pay e Google Pay: modificarla per il wallet significa modificarla anche per le carte.

MOTO

Per approfondire il funzionamento delle due modalità, consulta la sezione separazione tra autorizzazione e cattura.

Tokenizzazione​

Il metodo di pagamento utilizzato con Apple Pay può essere tokenizzato: Fabrick restituisce un token che rappresenta la carta scelta dal buyer nel proprio Wallet e che può essere riutilizzato per gli addebiti successivi, senza chiedere di nuovo i dati di pagamento.

La tokenizzazione si richiede nella chiamata payment/create, valorizzando il campo requestToken con MASKEDPAN.

È sufficiente la chiamata payment/create: Fabrick gestisce il pulsante Apple Pay, la generazione del Payment Token Package e la restituzione del token.

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",
    "paymentChannel": { "channelType": ["LINK"] }, // Solo per Pay By Link
    "requestToken": "MASKEDPAN"
}
Limitare la pagina a carta e wallet

Valorizzando paymentType con ["CREDITCARD"] la pagina di pagamento mostra la carta e i wallet abilitati sullo shopLogin, tra cui Apple Pay. La richiesta non cambia in base al metodo scelto dal buyer e il token restituito corrisponde al metodo utilizzato.

Il token è disponibile nella risposta di payment/detail, nel campo payload.tokenDetails.TokenValue.

Gestione del token

Per la lettura dei dati del token, la sua modifica e la cancellazione consulta Lettura dati token.

Pagamenti ricorrenti​

Apple Pay può essere utilizzato come metodo di pagamento di una serie ricorrente. Il buyer autorizza il primo pagamento della serie (First, CIT) con la propria autenticazione, mentre i pagamenti successivi (Next, MIT) vengono eseguiti dall'esercente in sua assenza, utilizzando il token ottenuto durante la First.

TransazioneIntegrazioni disponibiliDati da inviare
First (CIT)Integrazioni hosted oppure API OnlyPayload Apple Pay, come oggetto o come stringa, oppure un token già esistente
Next (MIT)APIToken generato o utilizzato nella First
I wallet sono gestiti come carte

Nelle transazioni Next il token va sempre inviato nel campo paymentTypeDetails.creditcard.token, anche quando la First è stata pagata con Apple Pay. Il flusso Next è quindi identico a quello della carta.

Per il flusso completo, i campi obbligatori della First, i dati da salvare e la gestione del soft decline 8026 consulta Pagamenti ricorrenti con carta e wallet.

Assistenza​

Fabrick

Apple