Cycle de vie d'une transaction de paiement

Découvrez comment les marchands intègrent des applications de paiement et comment fonctionnent les transactions de paiement avec l'API Payment Request.

Eiji Kitamura

Milica Mihajlija

Les API Web Payments sont des fonctionnalités de paiement dédiées intégrées au navigateur pour la première fois. Avec les paiements Web, l'intégration des marchands aux applications de paiement devient plus simple, tandis que l'expérience client est simplifiée et plus sécurisée.

Pour en savoir plus sur les avantages des paiements Web, consultez la page Autoriser les applications de paiement avec les paiements Web.

Cet article vous explique comment effectuer une transaction de paiement sur le site Web d'un marchand et comment fonctionne l'intégration d'une application de paiement.

Le processus comporte six étapes:

1. Le marchand effectue une transaction de paiement.
2. Le marchand affiche un bouton de paiement.

3. Le client appuie sur le bouton de paiement.

   

4. Le navigateur lance l'application de paiement.

   

5. Si le client modifie des détails (tels que les options de livraison ou son adresse), le marchand met à jour les détails de la transaction en conséquence.

   

6. Une fois que le client a confirmé l'achat, le marchand valide le paiement et finalise la transaction.

   

Étape 1: Le marchand initie une transaction de paiement

Lorsqu'un client décide d'effectuer un achat, le marchand initie la transaction de paiement en créant un objet PaymentRequest. Cet objet contient des informations importantes sur la transaction:

• Modes de paiement acceptés et leurs données permettant de traiter la transaction
• Détails, tels que le prix total (obligatoire) et des informations sur les articles
• Options permettant aux marchands de demander des informations de livraison, telles qu'une adresse et une option de livraison
• Les marchands peuvent également demander l'adresse de facturation, le nom, l'adresse e-mail et le numéro de téléphone du payeur.
• Les marchands peuvent également inclure un type de livraison facultatif (shipping, delivery ou pickup) dans le PaymentRequest. L'application de paiement peut s'en servir comme indication pour afficher les bons libellés dans son UI.

const request = new PaymentRequest([{
  supportedMethods: 'https://bobpay.xyz/pay',
  data: {
    transactionId: '****'
  }
}], {
  displayItems: [{
    label: 'Anvil L/S Crew Neck - Grey M x1',
    amount: { currency: 'USD', value: '22.15' }
  }],
  total: {
    label: 'Total due',
    amount: { currency: 'USD', value : '22.15' }
  }
}, {
  requestShipping: true,
  requestBillingAddress: true,
  requestPayerEmail: true,
  requestPayerPhone: true,
  requestPayerName: true,
  shippingType: 'delivery'
});

Inclure un ID de transaction

Certains gestionnaires de paiement peuvent demander au marchand de fournir l'ID de transaction qu'ils ont émis à l'avance dans les informations de transaction. Une intégration type comprend la communication entre le marchand et le serveur du gestionnaire de paiement pour réserver le prix total. Cela empêche les clients malveillants de manipuler le prix et de tromper le marchand grâce à une validation à la fin de la transaction.

Le marchand peut transmettre un ID de transaction dans la propriété data de l'objet PaymentMethodData.

Lorsque les informations de la transaction sont fournies, le navigateur passe par un processus de découverte des applications de paiement spécifiées dans le PaymentRequest en fonction des identifiants des modes de paiement. De cette façon, le navigateur peut déterminer l'application de paiement à lancer dès que le marchand est prêt à poursuivre la transaction.

Pour en savoir plus sur le fonctionnement du processus de découverte, consultez Configurer un mode de paiement.

Étape 2: Le marchand affiche un bouton de paiement

Les marchands peuvent accepter de nombreux modes de paiement, mais ils ne doivent présenter les boutons de paiement que pour ceux qu'un client peut réellement utiliser. Afficher un bouton de paiement inutilisable est une mauvaise expérience utilisateur. Si un marchand peut prédire qu'un mode de paiement spécifié dans l'objet PaymentRequest ne fonctionnera pas pour le client, il peut lui proposer une solution de remplacement ou ne pas afficher ce bouton du tout.

À l'aide d'une instance PaymentRequest, un marchand peut demander si un client dispose de l'application de paiement.

Le client dispose-t-il de l'application de paiement ?

La méthode canMakePayment() de PaymentRequest renvoie true si une application de paiement est disponible sur l'appareil du client. "Disponible" signifie qu'une application de paiement compatible avec le mode de paiement est détectée, et que l'application de paiement spécifique à la plate-forme est installée ou que l'application de paiement Web est prête à être enregistrée.

const canMakePayment = await request.canMakePayment();
if (!canMakePayment) {
  // Fallback to other means of payment or hide the button.
}

Étape 3: Le client appuie sur le bouton de paiement

Lorsque le client appuie sur le bouton de paiement, le marchand appelle la méthode show() de l'instance PaymentRequest, ce qui déclenche immédiatement le lancement de l'UI de paiement.

Si le prix total final est défini de manière dynamique (par exemple, récupéré sur un serveur), le marchand peut différer le lancement de l'interface de paiement jusqu'à ce que le total soit connu.

Reporter le lancement de l'UI de paiement

Regardez une démonstration expliquant comment différer l'interface utilisateur de paiement jusqu'à ce que le prix total final soit déterminé.

Pour différer l'UI de paiement, le marchand transmet une promesse à la méthode show(). Le navigateur affiche un indicateur de chargement jusqu'à ce que la promesse soit résolue et que la transaction soit prête à commencer.

const getTotalAmount = async () => {
  // Fetch the total amount from the server, etc.
};

try {
  const result = await request.show(getTotalAmount());
  // Process the result…
} catch(e) {
  handleError(e);
}

Si aucune promesse n'est spécifiée en tant qu'argument pour show(), le navigateur lance immédiatement l'interface utilisateur de paiement.

Remarque : Si le gestionnaire de paiement est conçu pour renvoyer un ID de transaction au moment de définir le prix total, cet ID peut être transmis dans le résultat de la promesse.

Étape 4: Le navigateur lance l'application de paiement

Le navigateur peut lancer une application de paiement spécifique à une plate-forme ou Web (découvrez comment Chrome détermine quelle application de paiement lancer).

La manière dont l'application de paiement est conçue dépend en grande partie du développeur. Toutefois, les événements émis par et vers le marchand, ainsi que la structure des données transmises avec ces événements, sont standardisés.

Lorsque l'application de paiement est lancée, elle reçoit les informations de transaction transmises à l'objet PaymentRequest à l'étape 1, qui incluent les éléments suivants:

• Données du mode de paiement
• Prix total
• Options de paiement

L'application de paiement utilise les informations de transaction pour étiqueter son UI.

Étape 5: Comment un marchand peut-il modifier les détails de la transaction en fonction des actions du client ?

Les clients ont la possibilité de modifier les détails de la transaction, tels que le mode de paiement et l'option de livraison dans l'application de paiement. Pendant que le client effectue des modifications, le marchand reçoit les événements de modification et met à jour les détails de la transaction.

Un marchand peut recevoir quatre types d'événements:

• Événement de modification du mode de paiement
• Événement de modification de l'adresse de livraison
• Événement de modification de l'option de livraison
• Événement de validation du marchand

Événement de modification du mode de paiement

Une application de paiement peut accepter plusieurs modes de paiement. Un marchand peut proposer une remise spéciale en fonction du choix du client. Pour couvrir ce cas d'utilisation, l'événement de modification du mode de paiement peut informer le marchand du nouveau mode de paiement afin qu'il puisse mettre à jour le prix total avec la remise et le renvoyer à l'application de paiement.

request.addEventListener('paymentmethodchange', e => {
  e.updateWith({
    // Add discount etc.
  });
});

Événement de modification de l'adresse de livraison

Une application de paiement peut éventuellement fournir l'adresse de livraison du client. Cette approche est pratique pour les clients, car ils n'ont pas besoin de saisir manuellement des informations dans un formulaire et peuvent stocker leur adresse de livraison dans leurs applications de paiement préférées, plutôt que sur plusieurs sites Web marchands différents.

Si un client met à jour son adresse de livraison dans une application de paiement après le lancement de la transaction, un événement 'shippingaddresschange' est envoyé au marchand. Cet événement permet au marchand de déterminer les frais de port en fonction de la nouvelle adresse, de mettre à jour le prix total et de le renvoyer à l'application de paiement.

request.addEventListener('shippingaddresschange', e => {
  e.updateWith({
    // Update the details
  });
});

Si le marchand ne peut pas livrer à l'adresse mise à jour, il peut fournir un message d'erreur en ajoutant un paramètre d'erreur aux détails de la transaction renvoyés à l'application de paiement.

Remarque : Les marchands ne reçoivent pas l'adresse de livraison complète des clients tant qu'ils n'ont pas autorisé le paiement.

Événement de modification de l'option de livraison

Un marchand peut proposer plusieurs options de livraison au client et déléguer ce choix à l'application de paiement. Les options de livraison s'affichent sous la forme d'une liste de prix et de noms de services que le client peut sélectionner. Exemple :

• Livraison standard sans frais
• Livraison express : 5 EUR

Lorsqu'un client met à jour l'option de livraison dans une application de paiement, un événement 'shippingoptionchange' est envoyé au marchand. Le marchand peut ensuite déterminer les frais de port, mettre à jour le prix total et le renvoyer à l'application de paiement.

request.addEventListener('shippingoptionchange', e => {
  e.updateWith({
    // Update the details
  });
});

Le marchand peut également modifier les options de livraison de manière dynamique en fonction de l'adresse de livraison du client. Cette option est utile lorsqu'un marchand souhaite proposer différents ensembles d'options de livraison à ses clients nationaux et internationaux.

Événement de validation du marchand

Pour plus de sécurité, une application de paiement peut effectuer une validation du marchand avant de passer au flux de paiement. La conception du mécanisme de validation dépend de l'application de paiement, mais l'événement de validation du marchand sert à informer le marchand de l'URL qu'il peut utiliser pour se valider lui-même.

request.addEventListener('merchantvalidation', e => {
  e.updateWith({
    // Use `e.validateURL` to validate
  });
});

Remarque : La prise en charge de l'événement de validation du marchand est limitée à Apple Safari. Les navigateurs basés sur Chromium n'ont pas implémenté cet événement depuis mai 2020.

Étape 6: Le marchand valide le paiement et finalise la transaction

Lorsque le client a autorisé le paiement, la méthode show() renvoie une promesse qui se résout en PaymentResponse. L'objet PaymentResponse inclut les informations suivantes:

• Détails des résultats de paiement
• Adresse de livraison
• Option de livraison
• Coordonnées

À ce stade, l'interface utilisateur du navigateur peut encore afficher un indicateur de chargement, indiquant que la transaction n'est pas encore terminée.

Si l'application de paiement est arrêtée en raison d'un échec de paiement ou d'une erreur, la promesse renvoyée par show() est refusée, et le navigateur y met fin.

Traitement et validation du paiement

details dans PaymentResponse est l'objet d'identifiant de paiement renvoyé par l'application de paiement. Le marchand peut utiliser cet identifiant pour traiter ou valider le paiement. C'est le gestionnaire de paiement qui décide du fonctionnement de ce processus critique.

Finaliser ou relancer la transaction

Une fois que le marchand a déterminé si la transaction a abouti ou échoué, il peut:

• Appelez la méthode .complete() pour terminer la transaction et ignorer l'indicateur de chargement.
• Laissez le client réessayer en appelant la méthode retry().

async function doPaymentRequest() {
  try {
    const request = new PaymentRequest(methodData, details, options);
    const response = await request.show();
    await validateResponse(response);
  } catch (err) {
    // AbortError, SecurityError
    console.error(err);
  }
}

async function validateResponse(response) {
  try {
    const errors = await checkAllValuesAreGood(response);
    if (errors.length) {
      await response.retry(errors);
      return validateResponse(response);
    }
    await response.complete("success");
  } catch (err) {
    // Something went wrong…
    await response.complete("fail");
  }
}
// Must be called as a result of a click
// or some explicit user action.
doPaymentRequest();

Étapes suivantes

• Découvrez comment déclarer un identifiant de mode de paiement en détail dans Configurer un mode de paiement.
• Découvrez comment créer une application de paiement spécifique à une plate-forme dans le guide du développeur d'applications de paiement Android.
• Découvrez comment créer une application de paiement Web dans le guide du développeur d'applications de paiement Web.