Prérequis :
- Charitable Pro 1.8.16+
- Dons récurrents de bienfaisance 2.1.0+
La situation d'un donateur change. Peut-être que le mois prochain sera difficile et qu'il voudra réduire son don mensuel de 50 $ à 25 $, ou qu'une subvention de contrepartie est arrivée et qu'il aimerait augmenter son don annuel. Avant Charitable Recurring 2.1, la seule façon de gérer cela était d'annuler l'abonnement et de demander au donateur d'en commencer un nouveau, ce qui entraîne la perte de l'historique des paiements et le risque que le don ne revienne jamais.
Vous pouvez maintenant mettre à jour le montant et la période de facturation d'un don récurrent actif directement depuis votre administration WordPress, et le changement est synchronisé automatiquement avec Stripe. Le même abonnement reste en place, l'historique des paiements est donc préservé et le donateur conserve sa date de début d'origine.
Vous pouvez appliquer un changement immédiatement, ou envoyer d'abord au donateur un lien d'approbation sécurisé. Chaque changement est consigné dans votre journal d'audit, et les changements que vous effectuez dans le tableau de bord Stripe sont automatiquement synchronisés avec Charitable.

Quand l'utiliser
- Un donateur demande de modifier son montant – mettez-le à jour en quelques secondes au lieu d'annuler et de réabonner.
- Un donateur souhaite passer du mensuel à l'annuel (ou à toute autre période) – changez la période de facturation en place.
- Un changement nécessite l'approbation du donateur – envoyez un e-mail d'approbation et laissez le donateur confirmer avant que quoi que ce soit ne se produise sur Stripe.
- Quelqu'un a modifié l'abonnement dans le tableau de bord Stripe – Charitable récupère automatiquement le nouveau montant et la nouvelle période.
- Vous avez besoin d'un enregistrement de qui a changé quoi – chaque mise à jour est consignée dans les journaux de Charitable avec l'ancienne valeur, la nouvelle valeur et qui l'a effectuée.
Où le trouver
Ouvrez le don récurrent que vous souhaitez modifier :
Administration WordPress > Dons > Dons récurrents > (cliquez sur le don)

Dans la boîte Actions sur le don à droite, choisissez Mettre à jour l'abonnement dans le menu déroulant, puis cliquez sur le bouton Mettre à jour l'abonnement.
Le don doit utiliser la passerelle Stripe et être dans le statut Actif. Les abonnements mis en pause, annulés, terminés et en attente ne peuvent pas être modifiés, ce qui évite au donateur d'être surpris par un prélèvement inattendu.
Mise à jour d'un abonnement
La fenêtre Mettre à jour l'abonnement affiche l'abonnement actuel en haut, puis les champs que vous pouvez modifier.

1. Définir le nouveau montant et/ou la nouvelle période
- Nouveau montant – entrez n'importe quelle valeur de 1,00 à (en théorie) 999999,99. Laissez-le inchangé pour conserver le montant actuel.
- Nouvelle période de facturation – choisissez parmi quotidien, hebdomadaire, mensuel, trimestriel, semestriel ou annuel. Laissez la période actuelle pour la conserver.
Vous pouvez changer l'un ou l'autre. Le changement prend effet à la prochaine date de facturation du donateur ; son cycle actuel se termine normalement, et aucun prorata n'est appliqué.
2. Choisir comment le changement est appliqué
- Appliquer immédiatement – le changement est envoyé à Stripe immédiatement.
- Demander l'approbation du donateur – un changement en attente est stocké et le donateur reçoit un e-mail avec des liens sécurisés pour approuver et refuser. Rien ne change sur Stripe tant qu'il n'a pas approuvé.

3. Décider s'il faut notifier le donateur
La case à cocher Notifier le donateur de ce changement est cochée par défaut. Lorsqu'elle est cochée, le donateur reçoit un e-mail « Abonnement mis à jour » avec l'ancien et le nouveau montant ou période. Décochez-la pour les ajustements en back-office dont le donateur n'a pas besoin d'être informé.
Lorsque vous cliquez sur Mettre à jour l'abonnement, vous verrez un message de succès et le total des dons sera mis à jour sur la page.
Le flux d'approbation du donateur
Lorsque vous choisissez Demander l'approbation du donateur, le donateur reçoit un e-mail avec deux liens : un pour approuver le changement et un pour le refuser.

Quelques points à connaître sur le fonctionnement des liens d'approbation :
- Sécurisés et spécifiques au don. Chaque lien contient un jeton signé, lié à ce don exact. Un lien pour un don ne peut pas être utilisé pour un autre.
- Ils expirent. Les liens d'approbation sont valides pendant 7 jours. Après cela, le lien cesse de fonctionner et vous devrez réémettre la demande.
- Utilisation unique. Une fois que le donateur approuve ou refuse, le lien est utilisé. Cliquer à nouveau dessus n'a aucun effet.
- Une nouvelle demande remplace une ancienne. Si vous émettez un deuxième changement alors qu'un est encore en attente, la nouvelle demande remplace l'ancienne et l'ancien lien cesse de fonctionner.
Si le donateur clique sur Approuver, le changement est envoyé à Stripe et le don est mis à jour. S'il clique sur Refuser, l'abonnement reste exactement le même et le changement en attente est annulé.
Modifications apportées dans le tableau de bord Stripe
Si vous (ou un membre de votre équipe) modifiez le montant ou la période de facturation d'un abonnement directement dans le tableau de bord Stripe, Charitable en est informé et met à jour le don local pour qu'il corresponde. Cela se fait via le webhook Stripe que vous avez déjà configuré, il n'y a donc rien de plus à mettre en place. Cela signifie que l'enregistrement du don dans WordPress reste précis, quelle que soit la provenance de la modification.
Lecture du journal d'audit
Chaque changement d'abonnement est enregistré dans vos journaux Charitable, qu'il provienne d'une mise à jour d'administrateur, d'une approbation de donateur ou du tableau de bord Stripe.
Administration WordPress » Charitable » Outils » Journaux
Chaque entrée enregistre l'ancienne valeur, la nouvelle valeur, qui a effectué le changement et quand. Vous pouvez filtrer par ID de don pour voir l'historique complet d'un seul abonnement.
L'e-mail de notification au donateur
Par défaut, les donateurs reçoivent un e-mail « Abonnement mis à jour » après un changement réussi, détaillant ce qui a changé. Vous pouvez le personnaliser ou le désactiver depuis :
Administration WordPress » Charitable » Paramètres » E-mails

Deux e-mails sont liés à cette fonctionnalité :
- Abonnement mis à jour – envoyé au donateur après l'application d'un changement. Activé par défaut.
- Demande de changement d'abonnement – l'e-mail de demande d'approbation, envoyé lorsque vous choisissez « Demander l'approbation du donateur ».
Cliquez sur l'un ou l'autre e-mail pour modifier son sujet, son titre et son corps, ou pour le désactiver.
Conseils
- Utilisez Demander l'approbation du donateur pour tout changement que le donateur n'a pas explicitement demandé, afin qu'il ait toujours le dernier mot.
- Le statut Actif du don est requis. Si l'option Mettre à jour l'abonnement est manquante ou désactivée, vérifiez d'abord le statut de l'abonnement.
- Les modifications prennent effet au prochain cycle de facturation, pas immédiatement, de sorte que le donateur n'est jamais facturé deux fois pour la période en cours.
Référence du développeur
Le chemin de mise à jour complet est basé sur des hooks, vous pouvez donc intercepter, étendre ou réagir aux changements d'abonnement.
Filtres
| Filtre | Défaut | Objectif |
|---|---|---|
charitable_process_subscription_update_stripe | array( 'success' => false, 'message' => ... ) | Implémenté par Charitable Pro 1.8.16+. Reçoit le don récurrent et les modifications proposées, les envoie à Stripe et renvoie un tableau de résultats. L'endpoint de mise à jour de l'administrateur et le gestionnaire d'approbation du donateur l'appellent tous deux. |
charitable_recurring_confirmation_page_colors | couleurs de la marque | Couleurs pour la page de confirmation d'approbation/refus visible par le donateur. |
charitable_recurring_confirmation_page_heading | titre par action | Le titre affiché sur la page de confirmation. |
charitable_recurring_confirmation_page_message | message par action | Le message principal sur la page de confirmation. |
charitable_recurring_confirmation_page_button | bouton retour-accueil | Le bouton affiché sur la page de confirmation. |
charitable_recurring_confirmation_page_html | vide | Retourner du HTML personnalisé pour remplacer toute la page de confirmation. |
Actions
| Action | Arguments | Quand cela se déclenche |
|---|---|---|
charitable_recurring_subscription_updated | $donation, $changes, $old_values | Après une mise à jour réussie. Déclenche l'e-mail donateur « Abonnement mis à jour » lorsque cet e-mail est activé. |
charitable_recurring_subscription_change_requested | $donation, $pending_data, $raw_token | Lorsqu'un administrateur demande l'approbation du donateur. Déclenche l'e-mail de demande d'approbation. |
charitable_stripe_subscription_details_changed | $subscription, $stripe_object | Déclenché par le processeur de webhook de Pro lors d'un événement Stripe customer.subscription.updated. L'écouteur de synchronisation inverse lit le nouveau montant et la nouvelle période à partir de l'objet Stripe. |
Fonctions et classes utilitaires
charitable_recurring_update_local_subscription( $donation, $changes )– met à jour uniquement les métadonnées locales. Gère la distribution proportionnelle d'un nouveau montant pour une seule campagne et pour plusieurs campagnes.Charitable_Recurring_Subscription_Change_Handler::process_approval()– gère le clic d'approbation du donateur (?donation_id=X&token=Y&action=approve).Charitable_Recurring_Subscription_Change_Handler::process_denial()– gère le chemin de refus.Charitable_Recurring_Subscription_Change_Handler::cleanup_expired_pending_changes()– supprime les enregistrements de changements en attente expirés (s'exécute lors d'un événement planifié).Charitable_Gateway_Stripe_AM::$period_map– tableau statique mappant chaque période Charitable à unintervaletinterval_countStripe.Charitable_Gateway_Stripe_AM::update_subscription( $result, $donation, $changes )– la méthode derrière le filtre ; crée un Plan Stripe pour les nouveaux arguments et échange l'élément de l'abonnement avec celui-ci, sans proratisation.
Mappage des périodes
Le montant et la période que vous définissez correspondent au modèle de facturation de Stripe comme suit :
| Période Charitable | Intervalle Stripe | nombre d'intervalles |
|---|---|---|
| jour | jour | 1 |
| semaine | semaine | 1 |
| mois | mois | 1 |
| trimestre | mois | 3 |
| semestre | mois | 6 |
| année | année | 1 |
Jeton d'approbation
Le lien d'approbation utilise un jeton HMAC-SHA256 lié à l'ID du don, au moment où le changement a été proposé, et à un secret unique de 32 caractères. Les jetons expirent après 7 jours. Un compteur de tentatives répétées est stocké dans le transient charitable_sub_token_attempts_{donation_id}, et l'enregistrement du changement en attente est supprimé lors de l'approbation ou du refus afin qu'un lien ne puisse pas être réutilisé.
Exemples de personnalisation
Ajoutez une ligne de journal personnalisée chaque fois qu'un abonnement est mis à jour :
add_action( 'charitable_recurring_subscription_updated', function ( $donation, $changes, $old_values ) {
error_log( sprintf(
'Subscription #%d updated: %s',
$donation->ID,
wp_json_encode( $changes )
) );
}, 10, 3 );
Informez votre équipe sur Slack lorsqu'une approbation de donateur est demandée :
add_action( 'charitable_recurring_subscription_change_requested', function ( $donation, $pending_data, $raw_token ) {
my_slack_notify( sprintf(
'Approval requested for recurring donation #%d',
$donation->ID
) );
}, 10, 3 );
Personnalisez la page de confirmation du donateur :
add_filter( 'charitable_recurring_confirmation_page_colors', function ( $colors ) {
$colors['primary'] = '#16a34a';
return $colors;
} );
Connexes
- Dons récurrents – l'aperçu des dons récurrents dans Charitable.
- Passerelle Stripe – connexion et configuration de Stripe.





