Configurare un metodo di pagamento

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

Eiji Kitamura

Pubblicazione: 27 settembre 2017, Ultimo aggiornamento: 16 ottobre 2026

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

Se non hai mai utilizzato i pagamenti web, leggi prima la panoramica dei pagamenti web.

Tipi di app per pagamenti

Un metodo di pagamento può essere supportato da un'app per pagamenti Android, da un'app per pagamenti basata sul web o da entrambe:

• App per pagamenti Android:un'app installata che Chrome avvia con un intent Android. Chrome verifica il nome del pacchetto e il certificato di firma dell'app.
• App per pagamenti basata sul web:un service worker che Chrome avvia in una finestra modale. Gli utenti non devono installare nulla.

Le app per pagamenti Android sono disponibili in Chrome su Android e in WebView. Le app per pagamenti basate sul web sono disponibili in Chrome su tutte le piattaforme, ma non in WebView.

Se entrambi i tipi di app sono disponibili per un metodo di pagamento e il manifest dell'app web imposta prefer_related_applications su true, Chrome nasconde l'app per pagamenti basata sul web. In caso contrario, gli utenti potrebbero visualizzare entrambe le app nell'interfaccia utente di Payment Request e scegliere tra le due.

Supporto browser

Web Payments è costituito da diverse tecnologie e lo stato del supporto dipende dal browser.

Come un browser rileva un'app per pagamenti

Ogni app per pagamenti deve fornire quanto segue:

• Identificatore del metodo di pagamento basato su URL
• Manifest del metodo di pagamento (tranne quando l'identificatore del metodo di pagamento è fornito da una terza parte)
• Manifest dell'app web

La procedura di rilevamento inizia quando 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 manifest dell'app web dal manifest del metodo di pagamento e recupera il manifest dell'app web.
3. Il browser determina se avviare l'app per pagamenti del sistema operativo o l'app per pagamenti basata sul web dal manifest dell'app web.

Le sezioni successive spiegano in dettaglio come configurare il tuo metodo di pagamento in modo che i browser possano rilevarlo.

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 per pagamenti possono scegliere qualsiasi URL come identificatore del metodo di pagamento, purché ne abbiano il controllo e possano pubblicare contenuti e intestazioni HTTP arbitrari. In questo articolo, utilizzeremo https://bobbucks.dev/pay come identificatore del metodo di pagamento.

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 identifica le app per pagamenti che un commerciante decide di accettare. Gli identificatori dei metodi di pagamento vengono impostati come valore per la proprietà supportedMethods. Ad esempio:

[merchant] requests payment:

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

Passaggio 2: pubblica il file manifest del metodo di pagamento

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

Fornisci il manifest del metodo di pagamento

Quando un commerciante avvia una transazione di pagamento, il browser invia una richiesta HTTP HEAD all'URL dell'identificatore del metodo di pagamento. L'URL dell'identificatore del metodo di pagamento risponde con un'intestazione HTTP Link che rimanda all'URL in cui il browser può recuperare il manifest del metodo di pagamento.

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 manifest si trova in https://bobbucks.dev/pay/payment-manifest.json, l'intestazione della risposta includerà:

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

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

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

Il browser invia quindi una richiesta HTTP GET all'URL del manifest del metodo di pagamento. Il server risponde con il corpo del file manifest del metodo di pagamento.

Un manifest del metodo di pagamento ha due campi, default_applications e supported_origins.

Un file manifest del 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 manifest delle app web delle app per pagamenti supportate.

Passaggio 3: pubblica un manifest dell'app web

Un manifest dell'app web viene utilizzato per definire un'app web, come suggerisce il nome. Si tratta di un file manifest ampiamente utilizzato per definire un'app web progressiva (PWA).

Un tipico manifest dell'app web è simile al seguente:

[payment handler] /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
  },
  "payment": {
    "supported_delegations": ["shippingAddress", "payerName", "payerEmail", "payerPhone"]
  },
  "start_url": "/",
  "display": "standalone",
  "theme_color": "#3f51b5",
  "background_color": "#3f51b5",
  "prefer_related_applications": true,
  "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"
        }
      ]
    }
  ]
}

Chrome legge campi diversi a seconda del tipo di app per pagamenti. Per un'app per pagamenti Android, Chrome legge solo related_applications. Per un'app per pagamenti basata sul web, Chrome legge name, icons, serviceworker, payment e prefer_related_applications.

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

In che modo Chrome determina quale app per pagamenti avviare

Avvio dell'app per pagamenti specifica per la piattaforma

Per avviare l'app per pagamenti specifica della piattaforma, devono essere soddisfatte le seguenti condizioni:

• Il campo related_applications è specificato nel 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.
• L'app per pagamenti specifica per la piattaforma è installata e ha:
  • Un filtro per intent di org.chromium.intent.action.PAY.
  • Un identificatore del metodo di pagamento specificato come valore della proprietà org.chromium.default_payment_method_name.

Per maggiori dettagli su come configurare queste app, consulta la Guida per gli sviluppatori di app per pagamenti Android.

[payment handler] /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 prefer_related_applications è true e l'app per pagamenti specifica per la piattaforma è disponibile, Chrome nasconde l'app per pagamenti basata sul web. In caso contrario, Chrome cerca anche l'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 manifest dell'app web.

[payment handler] /manifest.json:

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

Il browser avvia l'app per pagamenti basata sul web inviando un evento paymentrequest al service worker. Il service worker non deve essere registrato in anticipo. Può essere registrato just-in-time.

Informazioni sulle ottimizzazioni speciali

Come i browser possono saltare la UI di Payment Request e lanciare direttamente un'app per pagamenti

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

La visualizzazione della UI di Payment Request prima del lancio di un'app per pagamenti aumenta il numero di passaggi necessari per completare un pagamento. Per ottimizzare il processo, il browser può delegare l'adempimento di queste informazioni alle app per pagamenti e avviare un'app per pagamenti direttamente senza mostrare l'interfaccia utente della richiesta di pagamento quando viene chiamato show().

Per lanciare direttamente un'app per pagamenti, devono essere soddisfatte le seguenti condizioni:

• show() viene attivato da un'attivazione dall'utente (ad esempio, un clic del mouse).
• Esiste una sola app per pagamenti che:
  • Supporta l'identificatore del metodo di pagamento richiesto.
  • Supporta tutte le informazioni di spedizione e di contatto richieste dal commerciante.

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

Le app per pagamenti basate sul web possono essere avviate senza che l'utente visiti esplicitamente il sito web dell'app per pagamenti e registri 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. Esistono due varianti per la tempistica di registrazione:

• Se all'utente viene mostrata la UI di Payment Request, l'app viene registrata just-in-time e avviata quando l'utente fa clic su Continua.
• Se la UI di Payment Request viene saltata, l'app per pagamenti viene registrata just-in-time e avviata direttamente. Per saltare la UI di Payment Request e lanciare un'app registrata just-in-time è necessaria un'attivazione dall'utente, che impedisce la registrazione imprevista di service worker multiorigine.

Crea un'app per pagamenti basata sul web

Quando il commerciante chiama show(), Chrome invia un evento paymentrequest al tuo service worker. Chiama openWindow() all'interno di respondWith() per mostrare la UI di pagamento, quindi risolvi con la risposta di pagamento.

Per l'API completa, consulta l'API Web-Based Payment Handler su MDN.

Passaggi successivi

• Guida per gli sviluppatori di app per pagamenti Android
• Fornire i dati di spedizione e di contatto da un'app per pagamenti Android