# Mise en attente des mises à jour Apprenez à gérer les échecs de paiement lors de la mise à jour des abonnements. La modification d’un *abonnement* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis) produit une nouvelle *facture* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice) lorsque : - L’abonnement requiert un paiement pour la première fois, comme en fin de période d’essai. - La période de facturation est modifiée. - La modification d’un abonnement entraîne un calcul au prorata et `proration_behavior=always_invoice`. De nombreuses mises à jour d’abonnement ne génèrent pas de nouvelles factures et ne déclenchent pas de mises à jour en attente, notamment : - Modifications de configuration (moyens de paiement, paramètres fiscaux, paramètres de relances) - Mises à jour des métadonnées sur les abonnements ou les éléments d’abonnement - Ajout ou mise à jour de bons de réduction ou de codes promotionnels qui s’appliquent aux factures futures - Ajustements du seuil de facturation - Définir le paramètre `cancel_at_period_end` sur `true` - Ajout de paiements ponctuels avec le paramètre `add_invoice_items` Ces mises à jour s’appliquent immédiatement, sans incidence sur les paiements. Pour obtenir une liste complète, consultez la page [Ce qui ne déclenche pas des facturations au prorata](https://docs.stripe.com/billing/subscriptions/prorations.md#no-prorations). Par défaut, Stripe applique les mises à jour, que le paiement de la nouvelle facture réussisse ou non. Si le paiement échoue, l’annulation des mises à jour doit être faite manuellement. Vous devez créer une nouvelle facture, y imputer les postes calculés au prorata, puis relancer le paiement. Cependant, avec la nouvelle fonctionnalité de mise en attente des mises à jour, vous pouvez effectuer des modifications aux abonnements uniquement si le paiement réussit pour la nouvelle facture. ## Before you begin Vous pouvez utiliser des mises à jour en attente si le [collection_method](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-collection_method) de l’abonnement est `charge_automatically` et que le moyen de paiement est l’un des suivants : - [Carte bancaire](https://docs.stripe.com/payments/cards.md) - [Link](https://docs.stripe.com/payments/link.md) - [Alipay](https://docs.stripe.com/payments/alipay.md) - [Amazon Pay](https://docs.stripe.com/payments/amazon-pay.md) - [Afterpay/Clearpay](https://docs.stripe.com/payments/afterpay-clearpay.md) - [Apple Pay](https://docs.stripe.com/apple-pay.md) - [Cash App Pay](https://docs.stripe.com/payments/cash-app-pay.md) - [EPS](https://docs.stripe.com/payments/eps.md) - [GoPay](https://docs.stripe.com/payments/gopay.md) - [Google Pay](https://docs.stripe.com/google-pay.md) - [Kakao Pay](https://docs.stripe.com/payments/kakao-pay/accept-a-payment.md) - [Klarna](https://docs.stripe.com/payments/klarna.md) - [Carte bancaire coréenne](https://docs.stripe.com/payments/kr-card/accept-a-payment.md) - [Naver Pay](https://docs.stripe.com/payments/naver-pay/accept-a-payment.md) - [Carte bancaire nigériane](https://docs.stripe.com/payments/ng-card/accept-a-payment.md) - [PayPal](https://docs.stripe.com/payments/paypal.md) - [PayTo](https://docs.stripe.com/payments/payto.md) - [Pix](https://docs.stripe.com/payments/pix.md) - [PromptPay](https://docs.stripe.com/payments/promptpay.md) - [Revolut Pay](https://docs.stripe.com/payments/revolut-pay.md) - [Satispay](https://docs.stripe.com/payments/satispay.md) - [Stablecoins et cryptomonnaie](https://docs.stripe.com/payments/stablecoin-payments.md) - [Swish](https://docs.stripe.com/payments/swish.md) - [TWINT](https://docs.stripe.com/payments/twint.md) - [UPI](https://docs.stripe.com/payments/upi.md) - [WeChat Pay](https://docs.stripe.com/payments/wechat-pay.md) ## Mettre à jour l'abonnement [Côté serveur] Vous pouvez mettre des mises à jour en attente avec les appels de [modification d’abonnement](https://docs.stripe.com/api/subscriptions/update.md), de [création de poste d’abonnement](https://docs.stripe.com/api/subscription_items/create.md) et de [modification de poste d’abonnement](https://docs.stripe.com/api/subscription_items/update.md). Lorsque vous effectuez la mise à jour, définissez le paramètre`payment_behavior=pending_if_incomplete`. L’exemple ci-dessous illustre l’ajout d’un nouveau tarif à un abonnement. Puisque `proration_behavior=always_invoice` est spécifié, une facture est créée et le paiement est tenté lors de la mise à jour. #### curl ```bash curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \ -u <>: \ -d "payment_behavior"="pending_if_incomplete" \ -d "proration_behavior"="always_invoice" \ -d "items[0][id]"="si_09IkI4u3ZypJUk5onGUZpe8O" \ -d "items[0][price]"="price_CBb6IXqvTLXp3f" ``` Si le paiement réussit, l’abonnement est mis à jour. Si le paiement échoue, l’objet `Subscription` renvoyé contient un hachage `pending_update` avec les modifications : ```json { "id": "sub_49ty4767H20z6a", "object": "subscription", "application_fee_percent": null, "pending_update": { "expires_at": 1571194285, "subscription_items": [ { "id": "si_09IkI4u3ZypJUk5onGUZpe8O", "price": "price_CBb6IXqvTLXp3f" } ] } } ``` ## Traiter les échecs de paiement [Côté client] Après avoir effectué les mises à jour, vérifiez le hachage `pending_update` sur l’abonnement ou écoutez l’événement `customer.subscription.updated` dans votre *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests). Si le hachage `pending_update` est renseigné, cela signifie que le paiement a échoué et que la mise à jour de votre abonnement n’est pas appliquée. Créez une logique pour gérer les échecs de paiement dus à des refus de paiement par carte et à des demandes d’authentification des clients : - En cas de refus de paiement par carte, [associez un nouveau moyen de paiement](https://docs.stripe.com/billing/subscriptions/overview.md#requires-payment-method) au client. Utilisez ensuite l’endpoint de [paiement](https://docs.stripe.com/api/invoices/pay.md) pour payer la facture générée par la mise à jour. - Pour l’authentification du client, suivez le flux [Action requise](https://docs.stripe.com/billing/subscriptions/overview.md#requires-action). En cas de paiement réussi, les modifications du hachage `pending_update` sont appliquées et l’état de la facture passe à `paid`. Si le paiement échoue à nouveau, le hachage `pending_update` reste dans l’abonnement avec la [date d’expiration](https://docs.stripe.com/billing/subscriptions/pending-updates.md#expiration) d’origine et aucune modification n’est appliquée. ## Optional: Annuler ou modifier les mises à jour en attente [Côté serveur] Pour annuler une mise à jour en attente, vous devez annuler la facture créée par la mise à jour. Vérifiez l’attribut de la [dernière facture](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-latest_invoice) dans l’abonnement pour retrouver l’ID de la facture, puis utilisez l’ID pour [annuler](https://docs.stripe.com/api/invoices/void.md) la facture. Vous pouvez [mettre à jour un abonnement](https://docs.stripe.com/billing/subscriptions/pending-updates.md#update-subscription) avec de nouvelles valeurs pour une mise à jour en attente. Cette opération met à jour les valeurs dans le hachage `pending_update`, annule la facture associée à la précédente mise à jour en attente et crée une nouvelle facture reflétant les valeurs mises à jour. Le paiement de cette nouvelle facture applique les mises à jour les plus récentes à l’abonnement. L’échec du paiement génère une nouvelle mise à jour en attente avec une nouvelle [date d’expiration](https://docs.stripe.com/billing/subscriptions/pending-updates.md#expiration) pour remplacer la mise à jour existante. ## Attributs pris en charge pour les mises à jour en attente Les mises à jour en attente ne prennent en charge que les attributs qui contrôlent le comportement de calcul au prorata ou génèrent de nouvelles factures. L’endpoint de [mise à jour d’abonnement](https://docs.stripe.com/api/subscriptions/update.md) prend en charge les attributs suivants : - `expand` - `payment_behavior` - `proration_behavior` - `proration_date` - `billing_cycle_anchor` - `items` - `price` - `quantity` - `trial_end` - `trial_from_plan` - `add_invoice_items` Les endpoints de [création de postes d’abonnement](https://docs.stripe.com/api/subscription_items/create.md) et [mise à jour de poste d’abonnement](https://docs.stripe.com/api/subscription_items/update.md) prennent en charge les attributs suivants : - `expand` - `payment_behavior` - `proration_behavior` - `proration_date` - `price` - `quantity` ## Mises à jour expirées Si vous ne prenez aucune mesure après l’échec d’une mise à jour, Stripe annule la facture et rejette la mise à jour après son expiration. L’heure `expired_at` d’une mise à jour en attente correspond à la première occurrence de la [fin de la période d’essai](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-trial_end) ou la [fin de la période items.current](https://docs.stripe.com/api/subscriptions/object.md##subscription_object-items-data-current_period_end) la plus proche. Cela s’applique si l’une ou l’autre de ces deux périodes est située dans les 23 heures suivant la demande de mise à jour. Dans le cas contraire, le délai d’expiration est de 23 heures à compter de la demande de mise à jour. Stripe annule aussi automatiquement la facture et supprime la mise à jour en suspens si l’un des événements suivants se produit : - L’abonnement atteint un seuil de facturation. - Une planification d’abonnement associée à l’abonnement migre vers une nouvelle phase. ## Événements de mise à jour en suspens Utilisez les [webhooks](https://docs.stripe.com/webhooks.md) pour écouter les événements suivants liés aux mises à jour en attente. Ces événements sont les mêmes, que vous utilisiez des objets `Customer` ou des objets `Account` configurés pour le client. | Événement | Objectif | | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer.subscription.updated` | Recevoir des notifications pour les abonnements, la vérification du hachage `pending_updates` et la [résolution des échecs de paiement](https://docs.stripe.com/billing/subscriptions/pending-updates.md#handling-failed-payments), le cas échéant. | | `customer.subscription.pending_update_applied` | Recevez des notifications lorsque les mises à jour en suspens sont appliquées afin que vous puissiez effectuer des actions supplémentaires comme le passage à un plan tarifaire supérieur ou inférieur, la mise en et hors service des services. | | `customer.subscription.pending_update_expired` | Recevoir des notifications lorsque les mises à jour en suspens expirent ou sont automatiquement annulées, et le cas échéant, essayer d’effectuer une nouvelle fois la mise à jour. | ## Mises à jour en suspens et planification d’abonnement Vous pouvez utiliser à la fois les mises à jour en attente et la [planification d’abonnement](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md) pour gérer les abonnements. Un changement de phase de planification annule une mise à jour en attente et annule la facture associée. Le cas échéant, relancez la demande de mise à jour après la transition de phase. ## Postes mesurés Si un abonnement comprend des articles facturés à l’usage, Stripe facture tout enregistrement d’utilisation sur la facture de mise à jour en attente. Cependant, si la mise à jour en attente expire avant le paiement correspondant, Stripe ignore cette consommation, ce qui empêche de la comptabiliser sur les prochaines factures. Si la mise à jour en attente supprime un tarif facturé à l’usage, Stripe ignore toute consommation enregistrée entre la création de la mise à jour en attente et le paiement de la facture qui en résulte. Vous ne pouvez pas facturer pour cette utilisation. Cependant, si l’abonnement comporte le paramétrage `billing_mode=flexible`, Stripe facture la consommation lors de la suppression d’un tarif facturé à l’usage.