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 produit une nouvelle facture 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.

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.

Avant de commencer

Vous pouvez utiliser les mises à jour en attente si la collection_method de l’abonnement est charge_automatically ou si le moyen de paiement de l’abonnement est soit une carte bancaire, soit Link.

Mettre à jour l'abonnement
Côté serveur

Vous pouvez mettre des mises à jour en attente avec les appels de modification d’abonnement, de création de poste d’abonnement et de modification de poste d’abonnement. Lorsque vous effectuez la mise à jour, définissez le paramètrepayment_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.

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 :

{
  "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. 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 au client. Utilisez ensuite l’endpoint de paiement pour payer la facture générée par la mise à jour.
Pour l’authentification du client, suivez le flux Action requise.

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 d’origine et aucune modification n’est appliquée.

FacultatifAnnuler ou modifier les mises à jour en attente
Côté serveur

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 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 et mise à jour de poste d’abonnement 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 ou la fin de la période items.current 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

Vous pouvez utiliser des webhooks pour écouter les événements relatifs aux mises à jour en attente suivants :

É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, 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 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.