Mises à jour de l'état des paiements

Les PaymentIntents sont mis à jour en fonction des actions effectuées par vos clients ou par les moyens de paiement. Votre intégration peut examiner un PaymentIntent pour déterminer l’état du processus de paiement et ainsi vous permettre d’entreprendre les actions commerciales appropriées ou de répondre aux états nécessitant une intervention supplémentaire.

Vous pouvez aussi utiliser le Dashboard Stripe pour configurer votre compte afin de recevoir des e-mails lors des changements d’état des paiements, par exemple à la réussite d’un paiement. Modifiez vos notifications par e-mail dans les paramètres de l’utilisateur.

États des paiements et états des PaymentIntent

La page Payments du Dashboard indique un état de paiement pour chaque paiement, que vous pouvez utiliser pour filtrer la liste. Cet état résume le paiement, mais n’inclut pas les détails supplémentaires fournis par l’état du PaymentIntent.

L’état d’un PaymentIntent suit l’état d’un paiement et indique si un paiement nécessite un traitement supplémentaire ou des actions de la part du client. Un paiement utilisant un PaymentIntent peut nécessiter un moyen de paiement, une confirmation ou une autre action pour aboutir. Dans le Dashboard, ces états correspondent à Incomplet.

Pour comprendre l’état incomplet d’un paiement, cliquez sur le paiement et utilisez Workbench Inspector pour afficher les détails du PaymentIntent au format JSON. Recherchez état pour voir la valeur exacte.

Le tableau suivant met en correspondance chaque état de PaymentIntent avec les états de paiement dans le Dashboard. Les cas particuliers tels que les tentatives expirées et les codes de refus de paiement spécifiques peuvent avoir une incidence sur cette correspondance. Utilisez l’API ou Workbench Inspector pour obtenir l’état officiel.

Gérer les actions suivantes

Certains moyens de paiement nécessitent des actions supplémentaires, comme l’authentification, pour finaliser le processus de paiement. Stripe.js les gère automatiquement lors de la confirmation du PaymentIntent, mais si vous disposez d’une intégration avancée, vous pouvez les gérer manuellement.

La propriété next_action du PaymentIntent expose la prochaine étape que votre intégration doit gérer pour finaliser le paiement. Les prochaines actions disponibles varient selon le moyen de paiement. Pour obtenir une liste complète, consultez la documentation de l’API.

Découvrez comment gérer les prochaines actions obligatoires d’un moyen de paiement.

Vérifier l’état du PaymentIntent côté client

Lorsqu’un paiement est effectué côté client avec la fonction confirmPayment, vous pouvez examiner le PaymentIntent renvoyé pour déterminer son état actuel :

(async () => {
  const {paymentIntent, error} = await stripe.confirmPayment({
    elements,
    confirmParams: {
      return_url: 'https://example.com/order/complete',
    },
    redirect: 'if_required',
  });
  if (error) {
    // Handle error here
  } else if (paymentIntent && paymentIntent.status === 'succeeded') {
    // Handle successful payment here
  }
})();

Voici les résultats possibles lorsque la fonction confirmPayment est utilisée :

L’annonce renvoyée par la fonction confirmPayment aboutit lorsque le processus de paiement est soit réussi, soit en échec et associé à une erreur. Lorsque le paiement réussit et renvoie un PaymentIntent, l’état est toujours succeeded (ou requires_capture en cas de capture ultérieure). Lorsque le paiement nécessite une action supplémentaire, par exemple une authentification, l’annonce n’aboutit qu’une fois cette action effectuée ou le délai passé.

Vérifier l’état du PaymentIntent côté client sans utiliser confirmPayment

Pour vérifier l’état d’un PaymentIntent sans utiliser la fonction confirmPayment, récupérez-le séparément à l’aide de la fonction retrievePaymentIntent en transmettant la clé secrète du client.

(async () => {
  const {paymentIntent} = await stripe.retrievePaymentIntent(clientSecret);
  if (paymentIntent && paymentIntent.status === 'succeeded') {
    // Handle successful payment here
  } else {
    // Handle unsuccessful, processing, or canceled payments and API errors here
  }
})();

Voici quelques états possibles d’un PaymentIntent après confirmation :

En savoir plus sur les états des Paymentintents.

Suivre un PaymentIntent avec des webhooks

Stripe peut envoyer des événements webhook à votre serveur pour vous informer du changement d’état d’un PaymentIntent, ce qui est notamment utile pour déterminer quand fournir les biens ou les services.

Ne tentez pas de gérer la réalisation d’une commande côté client, car vos clients peuvent quitter la page après la finalisation du règlement, mais avant le début du processus de réalisation de la commande. Utilisez donc plutôt des webhooks pour surveiller l’événement payment_intent.succeeded et gérer son exécution de manière asynchrone au lieu de tenter de réaliser la commande côté client.

Pour gérer un événement webhook, créez un chemin sur votre serveur et configurez l’endpoint d’un webhook correspondant dans le Dashboard. Stripe envoie l’événement payment_intent.succeeded lorsque le paiement réussit et l’événement payment_intent.payment_failed lorsque le paiement échoue.

La charge utile du webhook inclut l’objet PaymentIntent. L’exemple suivant montre comment gérer les deux événements :

require 'sinatra'
require 'stripe'

post '/webhook' do
    payload = request.body.read
    sig_header = request.env['HTTP_STRIPE_SIGNATURE']
    event = nil

    begin
        event = Stripe::Webhook.construct_event(
            payload, sig_header, endpoint_secret
        )
    rescue JSON::ParserError => e
        # Invalid payload
        status 400
        return
    rescue Stripe::SignatureVerificationError => e
        # Invalid signature
        status 400
        return
    end

    case event['type']
    when 'payment_intent.succeeded'
        intent = event['data']['object']
        puts "Succeeded:", intent['id']
        # Fulfill the customer's purchase
    when 'payment_intent.payment_failed'
        intent = event['data']['object']
        error_message = intent['last_payment_error'] && intent['last_payment_error']['message']
        puts "Failed:", intent['id'], error_message
        # Notify the customer that payment failed
    end

    status 200
end

Lorsque le paiement échoue, vous pouvez trouver des informations en examinant la propriété last_payment_error du PaymentIntent. Vous pouvez informer votre client de l’échec du paiement et l’inviter à réessayer avec un autre moyen de paiement. Réutilisez ensuite le même PaymentIntent pour continuer à suivre l’achat de votre client.

Gérer des événements de webhook spécifiques

La liste suivante décrit comment gérer différents événements de webhook :

Pour tester des webhooks localement, vous pouvez utiliser l’interface de ligne de commande Stripe. Après l’avoir installée, vous pouvez transférer les événements à votre serveur :

stripe listen --forward-to localhost:4242/webhook
Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)

En savoir plus sur la configuration des webhooks.

Identifier les paiements d’un PaymentIntent

Lorsque vous tentez d’encaisser le paiement d’un client, le PaymentIntent crée un API Charge. Pour accéder à l’identifiant du dernier paiement, inspectez la propriété latest_charge du PaymentIntent :

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new(
'sk_test_VePHdqKTYQjKNInc7u56JBrQ')

intent = client.v1.payment_intents.retrieve('{{PAYMENT_INTENT_ID}}')
latest_charge = intent.latest_charge

Pour voir tous les paiements associés à un PaymentIntent, y compris ceux qui n’ont pas abouti, affichez la liste de tous les paiements et spécifiez le paramètre payment_intent.

curl -G https://api.stripe.com/v1/charges \
  -u "
sk_test_VePHdqKTYQjKNInc7u56JBrQ
:" \
  -d "payment_intent=
{{PAYMENT_INTENT_ID}}"