Configurare un metodo di pagamento

Una transazione di pagamento tramite Web Payments inizia con la scoperta della tua app di pagamento. Scopri come configurare un metodo di pagamento e preparare la tua app di pagamento per consentire a commercianti e clienti di effettuare pagamenti.

Eiji Kitamura

Per essere utilizzata con l'API Payment Request, un'app di pagamento deve essere associata a un identificatore del metodo di pagamento. I commercianti che vogliono effettuare l'integrazione con un'app di pagamento utilizzeranno l'identificatore del metodo di pagamento per indicarlo al browser. Questo articolo illustra come funziona il rilevamento delle app di pagamento e come configurare la tua app di pagamento in modo che venga rilevata e richiamata correttamente da un browser.

Se non conosci il concetto di pagamenti web o il funzionamento di una transazione di pagamento tramite app di pagamento, leggi prima i seguenti articoli:

• Potenziare le app di pagamento con Web Payments
• Ciclo di vita di una transazione di pagamento

Supporto del browser

Web Payments consiste in diverse tecnologie e lo stato del supporto dipende dal browser.

	Chromium		Safari		Firefox
	Computer	Android	Computer	Dispositivo mobile	Computer/dispositivi mobili
API Payment Request	✔	✔	✔	✔
API Payment Gestori	✔	✔
App per pagamenti iOS/Android	✔	✔	✔*	✔*

Nota: *Safari supporta Apple Pay, ma non le app di pagamento di terze parti.

In che modo un browser rileva un'app di pagamento

Ogni app di pagamento deve fornire quanto segue:

• Identificatore del metodo di pagamento basato su URL
• File manifest del metodo di pagamento (tranne nei casi in cui l'identificatore del metodo di pagamento sia fornito da una terza parte)
• File manifest dell'app web

Il processo di scoperta ha inizio nel momento in cui un commerciante avvia una transazione:

1. Il browser invia una richiesta all'URL dell'identificatore del metodo di pagamento e recupera il manifest del metodo di pagamento.
2. Il browser determina l'URL del file manifest dell'app web dal file manifest del metodo di pagamento e recupera il file manifest dell'app web.
3. Il browser determina se avviare l'app di pagamento del sistema operativo o l'app di pagamento basata sul web dal file manifest dell'app web.

Le sezioni successive spiegano in dettaglio come impostare un metodo di pagamento personalizzato in modo che i browser possano trovarlo.

Passaggio 1: fornisci l'identificatore del metodo di pagamento

Un identificatore del metodo di pagamento è una stringa basata su URL. Ad esempio, l'identificatore di Google Pay è https://google.com/pay. Gli sviluppatori di app di pagamento possono scegliere qualsiasi URL come identificatore del metodo di pagamento, purché ne abbiano il controllo e possano pubblicare contenuti arbitrari. In questo articolo utilizzeremo https://bobbucks.dev/pay come identificatore del metodo di pagamento.

Nota: le app di pagamento possono supportare anche metodi di pagamento di terze parti.

In che modo i commercianti utilizzano l'identificatore del metodo di pagamento

Un oggetto PaymentRequest viene creato con un elenco di identificatori dei metodi di pagamento che identificano le app di pagamento che un commerciante decide di accettare. Gli identificatori dei metodi di pagamento vengono impostati come valore per la proprietà supportedMethods. Ad esempio:

[merchant] richiede il pagamento:

const request = new PaymentRequest([{
  supportedMethods: 'https://bobbucks.dev/pay'
}], {
  total: {
    label: 'total',
    amount: { value: '10', currency: 'USD' }
  }
});

Nota: i reindirizzamenti sono consentiti fino a tre volte all'interno dello stesso sito per un identificatore del metodo di pagamento in Chrome.

Passaggio 2: pubblica il file manifest del metodo di pagamento

Un file manifest del metodo di pagamento è un file JSON che definisce quale app di pagamento può utilizzare questo metodo di pagamento.

Fornisci il file manifest del metodo di pagamento

Quando un commerciante avvia una transazione di pagamento, il browser invia una richiesta GET HTTP all'URL dell'identificatore del metodo di pagamento. Il server risponde con il corpo manifest del metodo di pagamento.

Il file manifest di un metodo di pagamento ha due campi, default_applications e supported_origins.

Campi manifest del metodo di pagamento

Nome proprietà	Descrizione
default_applications (campo obbligatorio)	Un array di URL che rimandano a manifest delle app web in cui sono ospitate le app di pagamento. L'URL può essere relativo. Questo array deve fare riferimento al manifest di sviluppo, al manifest di produzione e così via.
supported_origins	Un array di URL che rimandano a origini che potrebbero ospitare app di pagamento di terze parti che implementano lo stesso metodo di pagamento. Tieni presente che un metodo di pagamento può essere implementato da più app di pagamento.

Un file manifest di un metodo di pagamento dovrebbe avere il seguente aspetto:

[gestore dei pagamenti] /payment-manifest.json:

{
  "default_applications": ["https://bobbucks.dev/manifest.json"],
  "supported_origins": [
    "https://alicepay.friendsofalice.example"
  ]
}

Quando il browser legge il campo default_applications, trova un elenco di link ai file manifest delle app web delle app di pagamento supportate.

Nota: a partire dalla versione 83 di Chrome, Chrome supporta un'unica app di pagamento predefinita per singolo metodo di pagamento.

Se vuoi, puoi indirizzare il browser per trovare il file manifest del metodo di pagamento in un'altra posizione

L'URL identificatore del metodo di pagamento può facoltativamente rispondere con un'intestazione Link che rimanda a un altro URL in cui il browser può recuperare il manifest del metodo di pagamento. Ciò è utile quando il file manifest di un metodo di pagamento è ospitato su un server diverso o quando l'app di pagamento è pubblicata da una terza parte.

Configura il server del metodo di pagamento in modo che risponda con un'intestazione HTTP Link con l'attributo rel="payment-method-manifest" e l'URL del manifest del metodo di pagamento.

Ad esempio, se il file manifest si trova in https://bobbucks.dev/payment-manifest.json, l'intestazione della risposta includerà:

Link: <https://bobbucks.dev/payment-manifest.json>; rel="payment-method-manifest"

L'URL può essere un nome di dominio completo o un percorso relativo. Controlla https://bobbucks.dev/pay/ per individuare il traffico di rete per visualizzare un esempio. Puoi utilizzare anche un comando curl:

curl --include https://bobbucks.dev/pay

Nota: scopri di più sulle pratiche relative ai metodi di pagamento nella documentazione di W3C.

Passaggio 3: pubblica un file manifest dell'app web

Un file manifest dell'app web viene utilizzato per definire un'app web come suggerito dal nome. È un file manifest molto usato per definire un'app web progressiva (PWA).

Il tipico file manifest dell'app web ha il seguente aspetto:

[gestore dei pagamenti] /manifest.json:

{
  "name": "Pay with Bobpay",
  "short_name": "Bobpay",
  "description": "This is an example of the Payment Handler API.",
  "icons": [
    {
      "src": "images/manifest/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "images/manifest/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
  "serviceworker": {
    "src": "service-worker.js",
    "scope": "/",
    "use_cache": false
  },
  "start_url": "/",
  "display": "standalone",
  "theme_color": "#3f51b5",
  "background_color": "#3f51b5",
  "related_applications": [
    {
      "platform": "play",
      "id": "com.example.android.samplepay",
      "min_version": "1",
      "fingerprints": [
        {
          "type": "sha256_cert",
          "value": "4C:FC:14:C6:97:DE:66:4E:66:97:50:C0:24:CE:5F:27:00:92:EE:F3:7F:18:B3:DA:77:66:84:CD:9D:E9:D2:CB"
        }
      ]
    }
  ]
}

Le informazioni descritte nel file manifest di un'app web vengono utilizzate anche per definire la modalità di visualizzazione di un'app di pagamento nell'interfaccia utente della richiesta di pagamento.

Campi manifest importanti delle app web

Nome proprietà	Descrizione
name (campo obbligatorio)	Utilizzato come nome dell'app per pagamenti.
icons (campo obbligatorio)	Utilizzata come icona dell'app per pagamenti. Queste icone vengono utilizzate solo da Chrome; altri browser potrebbero utilizzarle come icone di riserva se non le specifichi come parte dello strumento di pagamento.
serviceworker	Utilizzato per rilevare il service worker eseguito come app di pagamento basata sul web.
serviceworker.src	L'URL da cui scaricare lo script del service worker.
serviceworker.scope	Una stringa che rappresenta un URL che definisce l'ambito della registrazione di un service worker.
serviceworker.use_cache	L'URL da cui scaricare lo script del service worker.
related_applications	Utilizzato per rilevare l'app che funge da app di pagamento fornita dal sistema operativo. Scopri di più nella guida per gli sviluppatori di app di pagamento Android.
prefer_related_applications	Utilizzato per determinare quale app di pagamento lanciare quando sono disponibili sia un'app di pagamento fornita dal sistema operativo sia un'app di pagamento basata sul web.

Etichetta e icona dell'app di pagamento.

La proprietà name del file manifest dell'app web viene utilizzata come nome dell'app di pagamento, mentre la proprietà icons viene utilizzata come icona dell'app di pagamento.

In che modo Chrome determina quale app di pagamento lanciare

Lancio dell'app di pagamento specifica per la piattaforma

Per lanciare l'app di pagamento specifica per la piattaforma, devono essere soddisfatte le seguenti condizioni:

• Il campo related_applications è specificato nel file manifest dell'app web e:
  • L'ID pacchetto e la firma dell'app installata corrispondono, mentre la versione minima (min_version) nel file manifest dell'app web è inferiore o uguale alla versione dell'applicazione installata.
• Il campo prefer_related_applications è true.
• L'app per pagamenti specifica per la piattaforma è installata e ha:
  • Un filtro per intent di org.chromium.action.PAY.
  • Un identificatore del metodo di pagamento specificato come valore per la proprietà org.chromium.default_payment_method_name.

Consulta App di pagamento Android: guida per gli sviluppatori per ulteriori dettagli su come configurarli.

[gestore dei pagamenti] /manifest.json

"prefer_related_applications": true,
"related_applications": [{
  "platform": "play",
  "id": "xyz.bobpay.app",
  "min_version": "1",
  "fingerprints": [{
    "type": "sha256_cert",
    "value": "92:5A:39:05:C5:B9:EA:BC:71:48:5F:F2:05:0A:1E:57:5F:23:40:E9:E3:87:14:EC:6D:A2:04:21:E0:FD:3B:D1"
  }]
}]

Se il browser ha stabilito che è disponibile l'app di pagamento specifica della piattaforma, il flusso di rilevamento viene terminato qui. In caso contrario, vai al passaggio successivo: l'avvio dell'app per pagamenti basata sul web.

Avvio dell'app per pagamenti basata sul web

L'app per pagamenti basata sul web deve essere specificata nel campo serviceworker del file manifest dell'app web.

[gestore dei pagamenti] /manifest.json:

"serviceworker": {
  "src": "payment-handler.js"
}

Il browser avvia l'app di pagamento basata sul web inviando un evento paymentrequest al service worker. Non è necessario che il service worker sia già registrato in anticipo. Può essere registrato just-in-time.

Comprensione delle ottimizzazioni speciali

In che modo i browser possono saltare l'interfaccia utente della richiesta di pagamento e avviare direttamente un'app di pagamento

In Chrome, quando viene chiamato il metodo show() di PaymentRequest, l'API Payment Request mostra un'interfaccia utente fornita dal browser chiamata "UI richiesta di pagamento". Questa UI consente agli utenti di scegliere un'app di pagamento. Dopo aver premuto il pulsante Continua nell'interfaccia utente Richiesta di pagamento, viene avviata l'app di pagamento selezionata.

L'interfaccia utente per la richiesta di pagamento interviene prima di avviare l'app di pagamento.

Mostrare l'interfaccia utente Richiesta di pagamento prima di avviare un'app di pagamento aumenta il numero di passaggi necessari a un utente per completare un pagamento. Per ottimizzare il processo, il browser può delegare l'evasione di queste informazioni alle app di pagamento e avviare un'app di pagamento direttamente senza mostrare la UI della richiesta di pagamento quando show() viene chiamato.

Salta l'interfaccia utente della richiesta di pagamento e avvia direttamente l'app di pagamento.

Per avviare direttamente un'app di pagamento, devono essere soddisfatte le seguenti condizioni:

• show() viene attivato con un gesto dell'utente, ad esempio un clic del mouse.
• Esiste una sola app di pagamento che:
  • Supporta l'identificatore del metodo di pagamento richiesto.

Nota: al momento Safari supporta solo Apple Pay, quindi avvia sempre l'app direttamente, saltando l'UI di richiesta di pagamento.

Quando viene registrata la registrazione just-in-time (JIT) di un'app per pagamenti basata sul web?

Le app di pagamento basate sul web possono essere avviate senza che l'utente abbia precedentemente visitato il sito web dell'app di pagamento e registrato il service worker. Il service worker può essere registrato just-in-time quando l'utente sceglie di pagare con l'app per pagamenti basata sul web. Le tempistiche di registrazione sono due:

• Se viene mostrata all'utente l'interfaccia utente della richiesta di pagamento, l'app viene registrata just-in-time e avviata quando l'utente fa clic su Continua.
• Se l'interfaccia utente della richiesta di pagamento viene ignorata, l'app di pagamento viene registrata just-in-time e avviata direttamente. Ignorare l'interfaccia utente Richiesta di pagamento per avviare un'app registrata just-in-time richiede un gesto dell'utente, che impedisce la registrazione imprevista dei service worker multiorigine.

Nota: sebbene un singolo identificatore di metodo di pagamento possa supportare più app di pagamento, la registrazione JIT avviene solo quando il file manifest del metodo di pagamento rimanda a una singola app di pagamento.

Passaggi successivi

Ora che la tua app di pagamento è rilevabile, scopri come sviluppare un'app di pagamento specifica per la piattaforma e un'app per pagamenti basata sul web.

• App di pagamento Android: guida per gli sviluppatori
• Guida per gli sviluppatori di app di pagamento basate sul web