Gérer des informations de paiement facultatives avec un service worker

Découvrez comment adapter votre application de paiement Web aux paiements Web afin d'améliorer l'expérience utilisateur.

Une fois qu'une application de paiement basée sur le Web reçoit une demande de paiement et lance une transaction de paiement, le service worker sert de hub de communication entre le marchand et l'application de paiement. Cet article explique comment une application de paiement peut transmettre des informations sur le mode de paiement, l'adresse de livraison ou les coordonnées au marchand à l'aide d'un service worker.

Gérer les informations de paiement facultatives avec un service worker
Gestion des informations de paiement facultatives avec un service worker

Informer le marchand d'un changement de mode de paiement

Les applications de paiement sont compatibles avec plusieurs modes de paiement différents.

Client Mode de paiement Mode de paiement
A Émetteur de carte de crédit 1 ****1234
Émetteur de la carte de crédit 1 ****4242
Banque X ******123
B Émetteur de carte de crédit 2 ****5678
Banque X ******456

Par exemple, dans le tableau ci-dessus, le portefeuille Web du client A comporte deux cartes de crédit et un compte bancaire enregistrés. Dans ce cas, l'application gère trois instruments de paiement (****1234, ****4242 et ******123) et deux modes de paiement (Émetteur de carte de crédit 1 et Banque X). Lors d'une transaction, l'application de paiement peut permettre au client de choisir l'un des modes de paiement et de l'utiliser pour payer le marchand.

UI du sélecteur de mode de paiement
UI du sélecteur de mode de paiement

L'application de paiement peut indiquer au marchand le mode de paiement choisi par le client avant d'envoyer la réponse de paiement complète. Cela est utile, par exemple, lorsque le marchand souhaite diffuser une campagne de remise pour une marque de mode de paiement spécifique.

Avec l'API Payment Handler, l'application de paiement peut envoyer un événement "modification du mode de paiement" au marchand via un service worker pour l'informer du nouvel identifiant du mode de paiement. Le service worker doit appeler PaymentRequestEvent.changePaymentMethod() avec les informations du nouveau mode de paiement.

Informer le marchand d'un changement de mode de paiement
Informez le marchand d'un changement de mode de paiement.

Les applications de paiement peuvent transmettre un objet methodDetails en tant que deuxième argument facultatif pour PaymentRequestEvent.changePaymentMethod(). Cet objet peut contenir des informations sur le mode de paiement arbitraires requises pour que le marchand puisse traiter l'événement de modification.

[payment handler] service-worker.js


// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      
      case 'PAYMENT_METHOD_CHANGED':
        const newMethod = e.data.paymentMethod;
        const newDetails = e.data.methodDetails;
        // Redact or check that no sensitive information is passed in
        // `newDetails`.
        // Notify the merchant of the payment method change
        details =
          await payment_request_event.changePaymentMethod(newMethod, newDetails);
      

Lorsque le marchand reçoit un événement paymentmethodchange de l'API PaymentRequest, il peut mettre à jour les informations de paiement et répondre avec un objet PaymentDetailsUpdate.

[merchant]

request.addEventListener('paymentmethodchange', e => {
  if (e.methodName === 'another-pay') {
    // Apply $10 discount for example.
    const discount = {
      label: 'special discount',
      amount: {
        currency: 'USD',
        // The value being string complies the spec
        value: '-10.00'
      }
    };
    let total = 0;
    details.displayItems.push(discount);
    for (let item of details.displayItems) {
     total += parseFloat(item.amount.value);
    }
    // Convert the number back to string
    details.total.amount.value = total.toString();
  }
  // Pass a promise to `updateWith()` and send updated payment details
  e.updateWith(details);
});

Lorsque le marchand répond, la promesse renvoyée par PaymentRequestEvent.changePaymentMethod() est résolue avec un objet PaymentRequestDetailsUpdate.

[payment handler] service-worker.js


        // Notify the merchant of the payment method change
        details = await payment_request_event.changePaymentMethod(newMethod, newDetails);
        // Provided the new payment details,
        // send a message back to the frontend to update the UI
        postMessage('UPDATE_REQUEST', details);
        break;

Utilisez l'objet pour mettre à jour l'UI côté client. Consultez Refléter les informations de paiement mises à jour.

Informer le marchand d'un changement d'adresse de livraison

Les applications de paiement peuvent fournir l'adresse de livraison d'un client au marchand dans le cadre d'une transaction de paiement.

Cela est utile pour les marchands, car ils peuvent déléguer la collecte des adresses aux applications de paiement. Étant donné que les données d'adresse seront fournies au format de données standard, le marchand peut s'attendre à recevoir des adresses de livraison dans une structure cohérente.

De plus, les clients peuvent enregistrer leur adresse dans l'application de paiement de leur choix et la réutiliser pour différents marchands.

UI du sélecteur d'adresse de livraison
Interface utilisateur du sélecteur d'adresse de livraison

Les applications de paiement peuvent fournir une UI permettant de modifier une adresse de livraison ou de sélectionner des informations d'adresse préenregistrées pour le client lors d'une transaction de paiement. Lorsqu'une adresse de livraison est déterminée temporairement, l'application de paiement peut informer le marchand des informations d'adresse masquées. Cela offre aux marchands de nombreux avantages :

  • Un marchand peut déterminer si le client respecte les restrictions régionales pour expédier l'article (par exemple, uniquement en France).
  • Un marchand peut modifier la liste des options de livraison en fonction de la région de l'adresse de livraison (par exemple, livraison internationale standard ou express).
  • Un marchand peut appliquer les nouveaux frais de port en fonction de l'adresse et mettre à jour le prix total.

Avec l'API Payment Handler, l'application de paiement peut envoyer un événement "Modification de l'adresse de livraison" au marchand à partir du service worker pour l'informer de la nouvelle adresse de livraison. Le service worker doit appeler PaymentRequestEvent.changeShippingAddress() avec le nouveau service d'adresse.

Informer le marchand d'un changement d'adresse de livraison
Informer le marchand d'un changement d'adresse de livraison

[payment handler] service-worker.js

...
// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      
      case 'SHIPPING_ADDRESS_CHANGED':
        const newAddress = e.data.shippingAddress;
        details =
          await payment_request_event.changeShippingAddress(newAddress);
      

Le marchand recevra un événement shippingaddresschange de l'API PaymentRequest afin de pouvoir répondre avec la PaymentDetailsUpdate mise à jour.

[merchant]

request.addEventListener('shippingaddresschange', e => {
  // Read the updated shipping address and update the request.
  const addr = request.shippingAddress;
  const details = getPaymentDetailsFromShippingAddress(addr);
  // `updateWith()` sends back updated payment details
  e.updateWith(details);
});

Lorsque le marchand répond, la promesse PaymentRequestEvent.changeShippingAddress() renvoyée se résout avec un objet PaymentRequestDetailsUpdate.

[payment handler] service-worker.js


        // Notify the merchant of the shipping address change
        details = await payment_request_event.changeShippingAddress(newAddress);
        // Provided the new payment details,
        // send a message back to the frontend to update the UI
        postMessage('UPDATE_REQUEST', details);
        break;

Utilisez l'objet pour mettre à jour l'UI sur l'interface. Consultez Refléter les informations de paiement mises à jour.

Informer le marchand d'un changement d'option de livraison

Les options de livraison sont les modes de livraison que les marchands utilisent pour expédier les articles achetés à un client. Les options de livraison habituelles sont les suivantes:

  • Livraison gratuite
  • Livraison express
  • Les livraisons internationales
  • Livraison internationale premium

Chacune a son propre coût. En général, les méthodes/options plus rapides sont plus coûteuses.

Les marchands qui utilisent l'API Payment Request peuvent déléguer cette sélection à une application de paiement. L'application de paiement peut utiliser ces informations pour créer une UI et permettre au client de choisir une option de livraison.

UI du sélecteur d'options de livraison
IUG du sélecteur d'options de livraison

La liste des options de livraison spécifiées dans l'API Payment Request du marchand est propagée au service worker de l'application de paiement en tant que propriété de PaymentRequestEvent.

[merchant]]

const request = new PaymentRequest([{
  supportedMethods: 'https://bobbucks.dev/pay',
  data: { transactionId: '****' }
}], {
  displayItems: [{
    label: 'Anvil L/S Crew Neck - Grey M x1',
    amount: { currency: 'USD', value: '22.15' }
  }],
  shippingOptions: [{
    id: 'standard',
    label: 'Standard',
    amount: { value: '0.00', currency: 'USD' },
    selected: true
  }, {
    id: 'express',
    label: 'Express',
    amount: { value: '5.00', currency: 'USD' }
  }],
  total: {
    label: 'Total due',
    amount: { currency: 'USD', value : '22.15' }
  }
}, {  requestShipping: true });

L'application de paiement peut indiquer au marchand l'option de livraison choisie par le client. Cela est important pour le marchand et le client, car le prix total change également lorsque vous modifiez l'option de livraison. Le marchand doit être informé du dernier prix afin de pouvoir vérifier les paiements ultérieurement, et le client doit également être informé de ce changement.

Avec l'API Payment Handler, l'application de paiement peut envoyer un événement "modification de l'option de livraison" au marchand à partir du service worker. Le service worker doit appeler PaymentRequestEvent.changeShippingOption() avec le nouvel ID d'option de livraison.

Informer le marchand d'une modification d'option de livraison
Informez le marchand d'un changement d'option de livraison.

[payment handler] service-worker.js


// Received a message from the frontend
self.addEventListener('message', async e => {
  let details;
  try {
    switch (e.data.type) {
      
      case 'SHIPPING_OPTION_CHANGED':
        const newOption = e.data.shippingOptionId;
        details =
          await payment_request_event.changeShippingOption(newOption);
      

Le marchand recevra un événement shippingoptionchange de l'API Payment Request. Le marchand doit utiliser ces informations pour mettre à jour le prix total, puis répondre avec la PaymentDetailsUpdate mise à jour.

[merchant]]

request.addEventListener('shippingoptionchange', e => {
  // selected shipping option
  const shippingOption = request.shippingOption;
  const newTotal = {
    currency: 'USD',
    label: 'Total due',
    value: calculateNewTotal(shippingOption),
  };
  // `updateWith()` sends back updated payment details
  e.updateWith({ total: newTotal });
});

Lorsque le marchand répond, la promesse que PaymentRequestEvent.changeShippingOption() a renvoyée se résout avec un objet PaymentRequestDetailsUpdate.

[payment handler] service-worker.js


        // Notify the merchant of the shipping option change
        details = await payment_request_event.changeShippingOption(newOption);
        // Provided the new payment details,
        // send a message back to the frontend to update the UI
        postMessage('UPDATE_REQUEST', details);
        break;

Utilisez l'objet pour mettre à jour l'UI côté client. Consultez Refléter les informations de paiement mises à jour.

refléter les détails du mode de paiement mis à jour ;

Une fois que le marchand a terminé de mettre à jour les détails du mode de paiement, les promesses renvoyées par .changePaymentMethod(), .changeShippingAddress() et .changeShippingOption() seront résolues avec un objet PaymentRequestDetailsUpdate commun. Le gestionnaire de paiement peut utiliser le résultat pour refléter le prix total et les options de livraison mis à jour dans l'UI.

Les marchands peuvent renvoyer des erreurs pour plusieurs raisons :

  • Le mode de paiement n'est pas accepté.
  • L'adresse de livraison est située en dehors des régions acceptées.
  • L'adresse de livraison contient des informations non valides.
  • L'option de livraison n'est pas disponible pour l'adresse de livraison fournie ou pour une autre raison.

Utilisez les propriétés suivantes pour refléter l'état de l'erreur :

  • error : chaîne d'erreur lisible par l'utilisateur. Il s'agit de la meilleure chaîne à afficher pour les clients.
  • shippingAddressErrors : objet AddressErrors contenant une chaîne d'erreur détaillée par propriété d'adresse. Cela est utile si vous souhaitez ouvrir un formulaire permettant au client de modifier son adresse et que vous devez le diriger directement vers les champs non valides.
  • paymentMethodErrors: objet d'erreur spécifique au mode de paiement. Vous pouvez demander aux marchands de fournir une erreur structurée, mais les auteurs de la spécification Web Payments recommandent de conserver une chaîne simple.

Exemple de code

La plupart des exemples de code que vous avez vus dans ce document étaient des extraits de l'application exemple fonctionnelle suivante :

https://paymenthandler-demo.glitch.me

[payment handler] service worker

[payment handler] frontend

Pour essayer:

  1. Accédez à la page https://paymentrequest-demo.glitch.me/.
  2. Accédez au bas de la page.
  3. Appuyez sur le bouton Ajouter un mode de paiement.
  4. Saisissez https://paymenthandler-demo.glitch.me dans le champ Identifiant du mode de paiement.
  5. Appuyez sur le bouton Payer à côté du champ.