# Mises à jour de l'état des paiements

Surveiller et vérifier l'état des paiements, afin de pouvoir répondre aux paiements réussis et échoués.

Les *PaymentIntents* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods) 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](https://docs.stripe.com/get-started/account/teams.md#email-notifications) dans les [paramètres de l’utilisateur](https://dashboard.stripe.com/settings/user).

## États des paiements et états des PaymentIntent

La page [Payments](https://dashboard.stripe.com/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](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-status) 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](https://docs.stripe.com/workbench/overview.md#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.

| `État` du PaymentIntent | État du paiement | Description |
| --- | --- | --- |
| `requires_payment_method` | **Incomplet** | Se produit généralement s’il n’y a pas de [latest_charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge) ou si l’intention n’a pas dépassé l’étape d’encaissement. Selon le moyen de paiement, les montants et les erreurs, l’état du paiement peut également être **Partiellement payé**, **En attente de fonds** ou **Échoué**. |
| `requires_confirmation` | **Incomplet** | Se produit une fois que votre client a fourni ses informations de paiement et est prêt à confirmer. La plupart des intégrations ignorent cet état, car elles transmettent les informations du moyen de paiement au moment de la confirmation du paiement. |
| `requires_action` | **Incomplet** | Se produit lorsque le paiement nécessite des actions supplémentaires, telles que l’authentification avec [3D Secure](https://docs.stripe.com/payments/3d-secure.md). L’état de paiement dans le Dashboard peut également être **Partiellement payé**, **En attente de fonds** ou **Échoué** dans certaines conditions d’authentification ou d’erreur. |
| `processing` | **En attente** | Se produit lorsque les actions obligatoires sont terminées et que le paiement utilise un *moyen de paiement asynchrone* (Asynchronous payment methods can take up to several days to confirm whether the payment has been successful. During this time, the payment can't be guaranteed), comme les prélèvements bancaires. Le traitement de ces moyens de paiement peut prendre jusqu’à quelques jours. |
| `requires_capture` | **Non capturé** ou **Capture partielle** | Se produit si votre tunnel utilise [separate capture](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md). Si un montant quelconque est reçu pour l’intention, l’état est **Capture partielle**. Si aucun montant n’est reçu, l’état est **Non capturé**. |
| `succeeded` | **Réussi** | Un PaymentIntent avec un état `succeeded` signifie que le tunnel de paiement correspondant est terminé. Les fonds sont sur votre compte et vous pouvez traiter la commande.

Si la tentative de paiement échoue (par exemple, en raison d’un refus de paiement), l’état du PaymentIntent repasse à `requires_payment_method` pour rendre possible une nouvelle tentative de paiement.

Les remboursements, litiges et résultats ultérieurs sont répercutés sur le Paiement. Ces éléments peuvent modifier ce que vous voyez dans le Dashboard, même si le PaymentIntent reste `succeeded`. |
| `canceled` | **Annulé** | Se produit lorsque le paiement est annulé. Si l’intention a été annulée dans le cadre de l’échec d’un tunnel de facture et que le dernier paiement a échoué, l’état peut indiquer **Échoué**. |

## 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](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-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](https://docs.stripe.com/api.md#payment_intent_object-next_action-type).

Découvrez comment [gérer les prochaines actions obligatoires d’un moyen de paiement](https://docs.stripe.com/payments/payment-methods/overview.md).

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

Lorsqu’un paiement est effectué côté client avec la fonction [confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment), vous pouvez examiner le PaymentIntent renvoyé pour déterminer son état actuel :

```javascript
(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 :

| **Événement** | **Ce qui s’est passé** | **Intégration attendue** |
| --- | --- | --- |
| Aboutit à un PaymentIntent | Le client a effectué un paiement sur votre page de paiement | Informer le client que son paiement a abouti |
| Aboutit à une erreur | Le paiement du client a échoué sur votre page de paiement | Afficher un message d’erreur et inviter votre client à effectuer une nouvelle tentative de paiement |

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](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md)). 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](https://docs.stripe.com/js/payment_intents/retrieve_payment_intent) en transmettant la *clé secrète du client* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)).

```javascript
(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](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-status) d’un PaymentIntent après confirmation :

| **Ce qui s’est passé** | **État attendu du PaymentIntent** |
| --- | --- |
| Le client a effectué un paiement sur votre page de paiement | `succeeded` |
| Le client n’a pas effectué le paiement | `requires_action` |
| Le paiement du client a échoué sur votre page de paiement | `requires_payment_method` |

[En savoir plus sur les états des Paymentintents](https://docs.stripe.com/payments/paymentintents/lifecycle.md).

## Suivre un PaymentIntent avec des webhooks

Stripe peut envoyer des événements *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) à 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* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) 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.

> Vous pouvez utiliser le polling au lieu des webhooks pour surveiller les modifications causées par des opérations asynchrones (en récupérant de façon répétée un PaymentIntent pour vérifier son état), mais cette méthode est beaucoup moins fiable et risque de déclencher des limites de requêtes. Stripe applique des [limites de requêtes](https://docs.stripe.com/testing.md#rate-limits) sur les requêtes API, soyez donc prudent si vous utilisez le polling.

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](https://dashboard.stripe.com/account/webhooks). 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 :

#### Ruby

```ruby
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 :

| Événement | Description | Étapes suivantes |
| --- | --- | --- |
| `processing` | Le paiement du client a été correctement envoyé à Stripe. Ne s’applique qu’aux moyens de paiement pour lesquels la [confirmation de paiement](https://docs.stripe.com/payments/payment-methods.md#payment-notification) est différée. | Attendez que le paiement effectué réussisse ou échoue. |
| `succeeded` | Le paiement du client a abouti. | Traitez la commande de biens ou de services de votre client. |
| `amount_capturable_updated` | Le paiement du client est autorisé et prêt à être capturé. | Capturez les fonds disponibles pour le paiement. |
| `payment_failed` | Le paiement du client a été refusé par un réseau de cartes ou a expiré. | Contactez votre client par e-mail ou notification push pour l’inviter à fournir un autre moyen de paiement. |

Pour tester des webhooks localement, vous pouvez utiliser la [CLI Stripe](https://docs.stripe.com/cli.md). Après l’avoir installée, vous pouvez transférer les événements à votre serveur :

```bash
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](https://docs.stripe.com/webhooks.md).

## Identifier les paiements d’un PaymentIntent

Lorsque vous tentez d’encaisser le paiement d’un client, le PaymentIntent crée un API [Charge](https://docs.stripe.com/api/charges.md). Pour accéder à l’identifiant du dernier paiement, inspectez la propriété [latest_charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge) du PaymentIntent :

#### Ruby

```ruby

# 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('<<YOUR_SECRET_KEY>>')

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](https://docs.stripe.com/api/charges/list.md#list_charges-payment_intent) et spécifiez le paramètre `payment_intent`.

```curl
curl -G https://api.stripe.com/v1/charges \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "payment_intent={{PAYMENTINTENT_ID}}"
```