Cette page a été traduite par l'API Cloud Translation.

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.

Eiji Kitamura

Lorsqu'une application de paiement Web reçoit une demande de paiement et effectue un paiement transaction, le service worker effectue une action en tant que hub de communication entre le marchand et l'application de paiement. Ce post explique comment une application de paiement peut transmettre des informations sur le mode de paiement, adresse de livraison ou coordonnées du marchand par le biais d'un service worker.

Gérer les 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 carte de crédit 1	`****4242`
	Banque X	`******123`
B	Émetteur de carte de crédit 2	`****5678`
B	Banque X	`******456`

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

UI de l'outil de sélection du mode de paiement

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

L'API Payment Handler permet à l'application de paiement d'envoyer une notification de modification du mode de paiement. au marchand via un service worker afin de notifier le nouveau mode de paiement. identifiant. Le service worker doit appeler PaymentRequestEvent.changePaymentMethod() avec le nouveau mode de paiement des informations.

Informer 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 Les détails du mode de paiement arbitraire requis pour que le marchand puisse traiter la modification .

[gestionnaire de paiement] 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 la part de l'API API Request, il peut mettre à jour les détails du paiement et répondre avec un PaymentDetailsUpdate .

[marchand]

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 que PaymentRequestEvent.changePaymentMethod() renvoyé se résout avec une PaymentRequestDetailsUpdate .

[gestionnaire de paiement] 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 sur l'interface. Consultez la section Refléter les modifications détails du paiement.

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 d'une transaction de paiement.

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

De plus, les clients peuvent enregistrer leur adresse dans leur application de paiement préférée et la réutiliser pour différents marchands.

UI de l'outil de sélection de l'adresse de livraison

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

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

Avec l'API Payment Handler, l'application de paiement peut envoyer une "adresse de livraison" modifier" de la part du service worker pour informer le marchand de la nouvelle livraison adresse e-mail. Le service worker doit appeler PaymentRequestEvent.changeShippingAddress() par la nouvelle adresse objet.

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

[gestionnaire de paiement] 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);
      …

Terme clé : adresse masquée. Dans ce cas, il n'est pas nécessaire d'indiquer l'adresse de livraison complète au marchand, car cela présente un risque pour les clients confidentialité. Le marchand ne reçoit que les parties de l'adresse dont il a besoin pour déterminer les frais de port. Plus précisément, le navigateur effacera les champs organization, phone, recipient et addressLine de l'adresse fournie par l'application de paiement avant de déclencher l'événement shippingaddresschange dans le DOM du marchand.

Le marchand recevra un événement shippingaddresschange de la part du client API Request afin qu'elle puisse répondre avec le PaymentDetailsUpdate mis à jour.

[marchand]

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é se résout avec une PaymentRequestDetailsUpdate .

[gestionnaire de paiement] 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 la section Refléter les modifications détails du paiement.

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 à un paiement l'application. L'application de paiement peut utiliser les informations pour créer une UI et laisser le le client à choisir une option d'expédition.

UI de l'outil de sélection des options de livraison

La liste des options d'expédition spécifiées dans l'API Payment Request du marchand est transmis au service worker de l'application de paiement en tant que propriété PaymentRequestEvent

[marchand]

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 quelle option de livraison le client a choisi d'utiliser. sélectionné. C'est important pour le marchand comme pour le client, car la modification de l'option de livraison modifie également le prix total. Le marchand doit avoir besoin afin d'être informé du dernier prix qui sera utilisé ultérieurement pour la validation des paiements. le client doit également être informé du changement.

Avec l'API Payment Handler, l'application de paiement peut envoyer une "option de livraison" modifier" au marchand par le service worker. Le service worker doit appeler PaymentRequestEvent.changeShippingOption() avec le nouvel ID d'option de livraison.

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

[gestionnaire de paiement] 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 la part du client API Request. Le marchand doit utiliser ces informations pour mettre à jour le prix total puis répondez en indiquant PaymentDetailsUpdate

[marchand]

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() renvoyé se résout avec une PaymentRequestDetailsUpdate .

[gestionnaire de paiement] 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 sur l'interface. Consultez la section Refléter les modifications détails du paiement.

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 sont renvoyées. de .changePaymentMethod(), .changeShippingAddress() et .changeShippingOption() se résout avec un PaymentRequestDetailsUpdate . Le gestionnaire de paiement peut utiliser le résultat pour refléter le prix total mis à jour. et de livraison à l'interface utilisateur.

Remarque : L'objet PaymentRequestDetailsUpdate est transmis par le marchand et contient les informations exactes que le marchand a saisies dans l'objet PaymentDetailsUpdate via l'API Payment Request. Le meilleur moyen de s'assurer que les marchands vous fournissent les informations attendues est de fournir une documentation de qualité destinée aux développeurs, ou de fournir une bibliothèque JavaScript pour contrôler ces informations, ou les deux.

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 incorrectes.
Vous ne pouvez pas sélectionner l'option de livraison pour l'adresse de livraison indiquée ou une autre raison.

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

error: chaîne d'erreur lisible par l'humain. Il s'agit de la meilleure chaîne à afficher aux clients.
shippingAddressErrors: AddressErrors contenant une chaîne d'erreur détaillée par propriété d'adresse. C'est utile si vous souhaitez ouvrir un formulaire permettant au client de modifier son adresse et vous devez les pointer directement vers les champs non valides.
paymentMethodErrors: objet d'erreur spécifique au mode de paiement. Vous pouvez demander les marchands de fournir une erreur structurée, mais les auteurs des spécifications de paiements Web nous vous recommandons de choisir une chaîne simple.

Exemple de code

La plupart des exemples de code présentés dans ce document sont des extraits des application exemple fonctionnelle:

https://paymenthandler-demo.glitch.me

service worker [gestionnaire de paiement]

interface [gestionnaire de paiement]

Pour essayer:

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