Bonnes pratiques pour l'utilisation de SourcesObsolète

La flexibilité de l’API Sources vous aide à minimiser les modifications requises pour prendre en charge les moyens de paiement supplémentaires au fur et à mesure que vous les ajoutez.

Tunnel de paiement typique pour les paiements par carte bancaire

Dans un tunnel de paiement typique pour les paiements par carte bancaire (à l’exclusion de 3D Secure), votre intégration recueille les informations de la carte et crée une source, qu’elle utilise pour effectuer une demande de paiement. Parce qu’aucune action supplémentaire n’est requise de la part du client et que les paiements par carte bancaire fournissent une confirmation synchrone, nous pouvons confirmer immédiatement l’exécution réussie du paiement et la garantie des fonds—l’usage de webhooks n’est pas nécessaire.

L’usage obligatoire de webhooks

D’autres méthodes de paiement peuvent nécessiter une action supplémentaire de la part de votre client (par exemple, une redirection) avant qu’une source devienne chargeable et puisse être utilisée pour faire une demande de paiement (par exemple, iDEAL). Cette transition se fait généralement de manière asynchrone et peut même se produire après que le client a quitté votre site web. C’est pourquoi votre intégration doit s’appuyer sur des webhooks pour déterminer quand une source devient payante avant de créer une charge.

Stripe envoie les événements webhook suivants pour vous informer des changements d’état de la source :

De même, lorsque vous créez un paiement, certains moyens de paiement asynchrones peuvent avoir besoin de plusieurs jours pour la confirmation de la disponibilité des fonds et l’exécution du paiement, ce qui exige des webhooks afin de savoir quand vous pouvez confirmer et finalement traiter vos commandes.

Stripe envoie les événements webhook suivants pour vous informer des changements d’état d’un paiement :

Créer une intégration flexible

Pour assurer la flexibilité de votre processus de paiement et la prise en charge de plusieurs moyens de paiement, nous recommandons l’approche suivante :

Création de la source

Pour la création de sources, enregistrez l’identifiant de la source dans votre représentation de commande interne afin de pouvoir récupérer la commande lorsque vous recevez et traitez les webhooks source.chargeable. Veillez à indexer les objets de commande en fonction de cet attribut source pour une recherche efficace.

Création du paiement

La livraison du webhook source.chargeable débite la source. Lorsque vous recevez le webhook, récupérez votre représentation interne de la commande par une recherche basée sur l’identifiant de la source reçu et vérifiez que la commande est en attente de paiement.

Pour effectuer une demande de paiement, utilisez votre identifiant de commande interne comme une clé d’idempotence afin d’éviter toute condition de concurrence. De plus, si la source est réutilisable et vous voulez l’utiliser à nouveau, veillez à la rattacher à un Client avant de la débiter. Référez-vous aux guides Moyens de paiement à usage unique ou réutilisables et Sources et Clients pour en savoir plus sur la façon de gérer les sources à usage unique et réutilisables et sur leur interaction avec les clients.

Comme pour la création d’une source, enregistrez l’identifiant du paiement dans votre représentation interne de la commande afin de pouvoir récupérer la commande lorsque vous recevez et traitez les webhooks charge.succeeded.

Page de confirmation

Une fois que votre client a effectué les actions requises pour autoriser un paiement (par exemple en effectuant un virement avec redirection bancaire), vous devez lui présenter une page de confirmation lui indiquant l’état de sa commande. Pour ce faire, vous pouvez interroger la commande en interne.

La latence de livraison du webhook n’étant pas garantie, si vous voulez rationaliser davantage votre page de confirmation, vous pouvez interroger l’état de la source associée dans votre code côté client. Lorsque vous détectez que votre source est devenue chargeable (facturable), vous pouvez lancer la création d’un paiement en utilisant cette source sans attendre l’arrivée du webhook source.chargeable.

Notez que certains types de sources prennent quelques minutes (voire quelques jours) pour devenir chargeable. Si vous décidez d’interroger la source, nous vous recommandons d’arrêter à un moment donné et d’informer le client que sa commande est en attente d’une confirmation de paiement, puis de lui envoyer un e-mail de confirmation de paiement de manière asynchrone. Vous trouverez dans le tableau ci-dessous les messages que nous recommandons pour chaque état de source.

L’interrogation côté client s’arrête si le client quitte votre page. Cela signifie que vous devez également prendre en compte le webhook source.chargeable dans votre intégration pour vous assurer de ne pas perdre la trace de la commande de votre client.

Si vous utilisez Stripe.js, vous pouvez faire appel à stripe.retrieveSource() pour implémenter votre propre interrogation :

// In order-confirmation-page.js

const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

// After some amount of time, we should stop trying to resolve the order synchronously:
const MAX_POLL_COUNT = 10;
let pollCount = 0;

const pollForSourceStatus = async () => {
  const {source} = await stripe.retrieveSource({id: SOURCE_ID, client_secret: CLIENT_SECRET})
  if (source.status === 'chargeable') {
    // Make a request to your server to charge the Source.
    // Depending on the Charge status, show your customer the relevant message.
  } else if (source.status === 'pending' && pollCount < MAX_POLL_COUNT) {
    // Try again in a second, if the Source is still `pending`:
    pollCount += 1;
    setTimeout(pollForSourceStatus, 1000);
  } else {
    // Depending on the Source status, show your customer the relevant message.
  }
};

pollForSourceStatus();

Ce tableau contient des recommandations de messages éventuels destinés aux clients que vous pouvez afficher en fonction de l’état de la source.

Après avoir créé un paiement (et si l’utilisateur est toujours sur votre page de confirmation), vous pouvez afficher les messages suivants en fonction de l’état du paiement :

Confirmation de commande

Confirmez votre commande uniquement après avoir reçu le webhook charge.succeeded (Cela peut se produire instantanément, mais pas nécessairement). Envoyez un e-mail au client à ce moment-là parce que la confirmation de paiement peut prendre plusieurs jours pour les paiements asynchrones.

Annulations et échecs

Écoutez les webhooks source.canceled et source.failed et assurez-vous d’annuler la commande associée à la source concernée. Si vous suivez les bonnes pratiques ci-dessus, vous ne devriez jamais recevoir un webhook source.canceled pour des sources qui étaient précédemment chargeable (facturables) car votre gestionnaire source.chargeable aurait dû créer un paiement immédiatement, empêchant l’annulation de la source. Vous recevrez toujours des webhooks source.canceled pour des sources qui n’ont jamais été chargeable et qui sont restées pending (en attente), ce qui indique généralement que votre client a quitté votre tunnel de paiement prématurément. Vous pouvez également recevoir un webhook source.failed lorsque le client a refusé le paiement ou qu’une défaillance technique s’est produite au niveau du schéma de paiement.

Vous devez également écouter les webhooks charge.failed pour vous assurer d’annuler la commande associée au paiement reçu.

Pour chacun de ces événements, nous vous recommandons d’informer votre client de l’échec de sa commande et de l’inviter à se réengager dans votre tunnel de paiement, s’il le souhaite.