Documentación de Charitable

Aprende a sacar el máximo partido a Charitable con instrucciones claras y paso a paso.

Cambiar importes y periodos de facturación de donaciones recurrentes

Requiere:

  • Charitable Pro 1.8.16+
  • Donaciones recurrentes benéficas 2.1.0+

La situación de un donante cambia. Quizás el próximo mes sea ajustado y quieran reducir su donación mensual de 50 € a 25 €, o ha llegado una subvención equivalente y les gustaría aumentar su donación anual. Antes de Charitable Recurring 2.1, la única forma de manejarlo era cancelar la suscripción y pedir al donante que iniciara una nueva, lo que pierde el historial de pagos y corre el riesgo de que la donación nunca regrese.

Ahora puedes actualizar el importe y el periodo de facturación de una donación recurrente activa directamente desde tu administrador de WordPress, y el cambio se sincroniza automáticamente con Stripe. La misma suscripción permanece activa, por lo que se conserva el historial de pagos y el donante mantiene su fecha de inicio original.

Puedes aplicar un cambio inmediatamente o enviar primero al donante un enlace de aprobación seguro. Cada cambio se registra en tu registro de auditoría, y los cambios que realices en el Panel de Stripe se sincronizan automáticamente con Charitable.

El cuadro Acciones de donación en una donación recurrente con Actualizar suscripción seleccionado en el menú desplegable y el botón Actualizar suscripción debajo de él

Cuándo usarlo

  • Un donante solicita cambiar su importe: actualízalo en segundos en lugar de cancelar y volver a suscribirse.
  • Un donante quiere cambiar de mensual a anual (o a cualquier otro periodo): cambia el periodo de facturación sin modificar la suscripción.
  • Un cambio requiere la aprobación del donante: envía un correo electrónico de aprobación y deja que el donante confirme antes de que ocurra nada en Stripe.
  • Alguien editó la suscripción en el Panel de Stripe: Charitable recoge automáticamente el nuevo importe y periodo.
  • Necesitas un registro de quién cambió qué: cada actualización se registra en los registros de Charitable con el valor anterior, el nuevo valor y quién lo realizó.

Cómo encontrarlo

Abre la donación recurrente que deseas cambiar:

Administrador de WordPress > Donaciones > Donaciones recurrentes > (haz clic en la donación)

La lista de Donaciones recurrentes en el menú Charitable, que muestra las donaciones recurrentes con sus filtros de estado

En el cuadro Acciones de donación de la derecha, elige Actualizar suscripción en el menú desplegable y, a continuación, haz clic en el botón Actualizar suscripción.

La donación debe usar la pasarela de Stripe y estar en estado Activa. Las suscripciones pausadas, canceladas, completadas y pendientes no se pueden editar, lo que evita que el donante se sorprenda con un cargo inesperado.

Actualizar una suscripción

La ventana Actualizar suscripción muestra la suscripción actual en la parte superior, seguida de los campos que puedes cambiar.

La ventana Actualizar suscripción que muestra la suscripción actual, el campo Nuevo importe, el menú desplegable Nuevo período de facturación, las opciones Plazo de suscripción y Modo de actualización, y la casilla de verificación de notificación al donante

1. Establece el nuevo importe y/o periodo

  • Nuevo importe: introduce cualquier valor desde 1,00 hasta (en teoría) 999999,99. Déjalo sin cambios para mantener el importe actual.
  • Nuevo periodo de facturación: elige entre diario, semanal, mensual, trimestral, semestral o anual. Déjalo en el periodo actual para mantenerlo.

Puedes cambiar uno o ambos. El cambio entra en vigor en la próxima fecha de facturación del donante; su ciclo actual finaliza normalmente y no se aplica ningún prorrateo.

2. Elige cómo se aplica el cambio

  • Aplicar inmediatamente: el cambio se envía a Stripe de inmediato.
  • Solicitar aprobación del donante – se almacena un cambio pendiente y el donante recibe un correo electrónico con enlaces seguros para aprobar y denegar. Nada cambia en Stripe hasta que aprueben.
La ventana Actualizar suscripción con un nuevo importe de 40.00, un período de facturación Trimestral y Solicitar aprobación del donante seleccionado

3. Decidir si notificar al donante

La casilla Notificar al donante de este cambio está activada por defecto. Cuando está marcada, el donante recibe un correo electrónico de “Suscripción Actualizada” con el importe o período antiguo y nuevo. Desmárquela para ajustes de back-office de los que el donante no necesita tener conocimiento.

Cuando haga clic en Actualizar Suscripción, verá un mensaje de éxito y el total de la donación se actualizará en la página.

El flujo de trabajo de aprobación del donante

Cuando elige Solicitar aprobación del donante, el donante recibe un correo electrónico con dos enlaces: uno para aprobar el cambio y otro para denegarlo.

El correo electrónico Solicitud de cambio de suscripción que recibe un donante, con un enlace para Aprobar este cambio y un enlace para rechazar el cambio

Algunas cosas que vale la pena saber sobre cómo funcionan los enlaces de aprobación:

  • Seguros y específicos para la donación. Cada enlace lleva un token firmado vinculado a esa donación exacta. Un enlace para una donación no se puede usar en otra.
  • Caducan. Los enlaces de aprobación son válidos durante 7 días. Después de eso, el enlace deja de funcionar y tendría que volver a emitir la solicitud.
  • Un solo uso. Una vez que el donante aprueba o deniega, el enlace se agota. Hacer clic en él de nuevo no hace nada.
  • Una nueva solicitud reemplaza a una antigua. Si emite un segundo cambio mientras uno todavía está pendiente, la solicitud más reciente reemplaza a la anterior y el enlace antiguo deja de funcionar.

Si el donante hace clic en Aprobar, el cambio se envía a Stripe y la donación se actualiza. Si hace clic en Denegar, la suscripción permanece exactamente como estaba y el cambio pendiente se elimina.

Cambios realizados en el Panel de control de Stripe

Si usted (o un compañero de equipo) edita el importe o el período de facturación de una suscripción directamente en el Panel de control de Stripe, Charitable lo notifica y actualiza la donación local para que coincida. Esto ocurre a través del webhook de Stripe que ya tiene configurado, por lo que no hay nada adicional que configurar. Significa que el registro de la donación en WordPress se mantiene preciso sin importar dónde se realizó la edición.

Leer el registro de auditoría

Cada cambio de suscripción se registra en sus registros de Charitable, ya sea que provenga de una actualización de administrador, una aprobación de donante o el Panel de control de Stripe.

Panel de administración de WordPress » Charitable » Herramientas » Registros

Cada entrada registra el valor antiguo, el valor nuevo, quién realizó el cambio y cuándo. Puede filtrar por ID de donación para ver el historial completo de una sola suscripción.

El correo electrónico de notificación al donante

Por defecto, los donantes reciben un correo electrónico de “Suscripción Actualizada” después de un cambio exitoso, detallando lo que cambió. Puede personalizarlo o deshabilitarlo desde:

Panel de administración de WordPress » Charitable » Ajustes » Correos electrónicos

La lista de ajustes de Correos electrónicos de Charitable que muestra los correos electrónicos para el donante de Suscripción actualizada y Solicitud de cambio de suscripción

Dos correos electrónicos se relacionan con esta función:

  • Suscripción Actualizada – enviado al donante después de que se aplica un cambio. Activado por defecto.
  • Solicitud de Cambio de Suscripción – el correo electrónico de solicitud de aprobación, enviado cuando elige “Solicitar aprobación del donante”.

Haga clic en cualquiera de los correos electrónicos para editar su asunto, encabezado y cuerpo, o para desactivarlo.

Consejos

  • Usa Solicitar aprobación del donante para cualquier cambio que un donante no haya solicitado explícitamente, para que siempre tengan la última palabra.
  • Se requiere el estado Activo de la donación. Si la opción Actualizar suscripción falta o está desactivada, primero comprueba el estado de la suscripción.
  • Los cambios entran en vigor en el próximo ciclo de facturación, no de inmediato, por lo que el donante nunca se factura dos veces en el período actual.

Referencia del desarrollador

La ruta completa de actualización se basa en hooks, por lo que puedes interceptar, extender o reaccionar a los cambios de suscripción.

Filtros

FiltroPredeterminadoPropósito
charitable_process_subscription_update_stripearray( 'success' => false, 'message' => ... )Implementado por Charitable Pro 1.8.16+. Recibe la donación recurrente y los cambios propuestos, los envía a Stripe y devuelve un array de resultados. Tanto el endpoint de actualización de administrador como el manejador de aprobación del donante lo llaman.
charitable_recurring_confirmation_page_colorscolores de marcaColores para la página de confirmación de aprobación/denegación que ve el donante.
charitable_recurring_confirmation_page_headingencabezado por acciónEl encabezado que se muestra en la página de confirmación.
charitable_recurring_confirmation_page_messagemensaje por acciónEl mensaje del cuerpo en la página de confirmación.
charitable_recurring_confirmation_page_buttonbotón volver-a-inicioEl botón que se muestra en la página de confirmación.
charitable_recurring_confirmation_page_htmlvacíoDevuelve HTML personalizado para reemplazar toda la página de confirmación.

Acciones

AcciónArgumentosCuando se activa
charitable_recurring_subscription_updated$donation, $changes, $old_valuesDespués de una actualización exitosa. Activa el correo electrónico "Suscripción actualizada" para el donante cuando ese correo esté habilitado.
charitable_recurring_subscription_change_requested$donation, $pending_data, $raw_tokenCuando un administrador solicita la aprobación del donante. Activa el correo electrónico de solicitud de aprobación.
charitable_stripe_subscription_details_changed$subscription, $stripe_objectDisparado por el procesador de webhooks de Pro en un evento customer.subscription.updated de Stripe. El listener de sincronización inversa lee la nueva cantidad y el período del objeto Stripe.

Funciones y clases auxiliares

  • charitable_recurring_update_local_subscription( $donation, $changes ) – actualiza solo los metadatos locales. Maneja la distribución proporcional de una nueva cantidad para campañas únicas y múltiples.
  • Charitable_Recurring_Subscription_Change_Handler::process_approval() – maneja el clic de aprobación del donante (?donation_id=X&token=Y&action=approve).
  • Charitable_Recurring_Subscription_Change_Handler::process_denial() – maneja la ruta de denegación.
  • Charitable_Recurring_Subscription_Change_Handler::cleanup_expired_pending_changes() – elimina los registros de cambios pendientes caducados (se ejecuta en un evento programado).
  • Charitable_Gateway_Stripe_AM::$period_map – array estático que mapea cada período de Charitable a un interval y interval_count de Stripe.
  • Charitable_Gateway_Stripe_AM::update_subscription( $result, $donation, $changes ) – el método detrás del filtro; crea un Plan de Stripe para los nuevos argumentos y lo intercambia con la suscripción sin prorrateo.

Mapeo de períodos

La cantidad y el período que establezcas se mapean al modelo de facturación de Stripe de la siguiente manera:

Período de CharitableIntervalo de Stripeinterval_count
díadía1
semanasemana1
mesmes1
trimestremes3
semestremes6
añoaño1

Token de aprobación

El enlace de aprobación utiliza un token HMAC-SHA256 vinculado al ID de la donación, la hora en que se propuso el cambio y un secreto de 32 caracteres de un solo uso. Los tokens caducan después de 7 días. Un contador de intentos repetidos se almacena en el transitorio charitable_sub_token_attempts_{donation_id}, y el registro de cambios pendientes se elimina al aprobar o denegar para que un enlace no se pueda reproducir.

Ejemplos de personalización

Añade una línea de registro personalizada cada vez que se actualiza una suscripción:

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 );

Notifica a tu equipo en Slack cuando se solicite la aprobación de un donante:

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 );

Personaliza la página de confirmación del donante:

add_filter( 'charitable_recurring_confirmation_page_colors', function ( $colors ) {
    $colors['primary'] = '#16a34a';
    return $colors;
} );

Relacionado

¿Todavía tienes preguntas? ¡Estamos aquí para ayudarte!

Última modificación:

Novedades en Benéfico

Ver las últimas actualizaciones
🔔 Suscríbete para recibir nuestras últimas actualizaciones
📧 Suscribirse a correos electrónicos

Suscripción por correo electrónico

Únete a nuestro boletín

No te enviaremos spam. Solo enviamos un correo electrónico cuando creemos que realmente te ayudará. ¡Date de baja en cualquier momento!

Donaciones Nuevo

👥 Presentamos la fusión de donantes: ¡Dos registros, un colaborador!

En algún lugar de su lista de donantes hay un colaborador que aparece dos veces, porque un año donó desde una dirección de trabajo y al siguiente desde una personal. Cada donación se registra y cada recibo se envía, pero un colaborador leal que ha donado durante años puede parecer dos personas que donaron la mitad. A partir del plugin Charitable Pro 1.8.19.1, puede encontrar esos registros y fusionarlos desde la pantalla de Donantes. Por qué esto es importante:

  • 🔍 Un enlace para encontrar duplicados donde ya trabaja: Vaya a Charitable » Donantes y se encontrará junto a Filtrar y Exportar, luego le dirá cuántos grupos de posibles duplicados ha encontrado.
  • 🧩 Agrupados por nombre, no por correo electrónico: Charitable compara el nombre y el apellido juntos e ignora las mayúsculas, los espacios y la puntuación, que es lo que detecta a la misma persona bajo dos direcciones diferentes.
  • 📊 Una vista previa antes de que algo cambie: Cada grupo muestra cada registro con su dirección de correo electrónico, el número de donaciones y el total acumulado, y la vista previa le muestra los totales combinados y el correo electrónico que se agregará.
  • ↩️ Cada fusión se puede deshacer: Nada se fusiona hasta que usted decida fusionarlo, y puede revertir cualquier fusión después, por lo que una suposición incorrecta no le cuesta nada.
  • 📥 Creado para la semana posterior a una importación: La migración de donantes desde otro plugin es de donde provienen la mayoría de los duplicados, y también es cuando son más difíciles de detectar, porque cada registro es nuevo para usted.

Consulta nuestro anuncio aquí.

embajadores Nuevo

🔑 Presentamos Recaudadores sin Contraseña: ¡Regístrate solo con tu correo electrónico!

Los seguidores llegan queriendo ayudar, y luego el formulario les pide que inventen una contraseña para un sitio web que quizás solo visiten dos veces. Muchos de ellos se detienen ahí mismo. Las cuentas de recaudación de fondos sin contraseña, nuevas en Charitable Ambassadors 3.5.0, permiten a un seguidor iniciar una recaudación de fondos de persona a persona con solo una dirección de correo electrónico. Por qué esto es importante:

  • 🔑 Sin paso de contraseña para perderlos: Actívalo en Charitable » Ambassadors » Templates » Submit Form y el formulario de creación de recaudación de fondos solo pide un nombre, una dirección de correo electrónico y un título de página.
  • 👤 Sigue siendo una cuenta real de WordPress: Un clic en un correo electrónico confirma la dirección, los inicia y crea la cuenta, para que puedan volver más tarde a editar su historia, cambiar su foto y ver quién ha donado.
  • 🎚️ Tu decisión en cada campaña: Cada campaña de persona a persona puede seguir la configuración predeterminada del sitio o anularla, lo que importa cuando una campaña paga a los recaudadores de fondos a través de Stripe Connect y esas personas necesitan una contraseña.
  • 📋 Ver quién no ha hecho clic todavía: La pestaña Charitable » Ambassadors » Directory » Awaiting Sign-In enumera a todos los que aún esperan, con la campaña a la que se unieron y un botón de Reenviar, para que un error tipográfico o una carpeta de spam sea algo que puedas detectar y corregir.
  • 🛡️ Enlaces que un escáner no puede agotar: Abrir el enlace solo muestra una página, y tu recaudador de fondos inicia sesión cuando presiona el botón en él, por lo que los escáneres de correo electrónico corporativos nunca queman el enlace. Cada uno funciona una vez, expira por sí solo y se almacena solo como un hash.

Consulta nuestro anuncio aquí.

embajadores Nuevo

🏃 ¡Presentamos Actividad: Muestra el progreso en más que solo dinero!

La mayoría de las recaudaciones de fondos entre pares se centran en más que el dinero. Una maratón de lectura se basa en los minutos leídos, una caminata en las millas recorridas y una colecta de alimentos en las comidas preparadas. La Actividad para Embajadores Benéficos permite que tus recaudadores de fondos muestren ese esfuerzo junto a los dólares que recaudan. Por qué esto es importante:

  • 🎯 Progreso en lo que realmente cuentas: Una barra de progreso muestra cada cosa que cuentas contra su propio objetivo, justo al lado del dinero recaudado.
  • 🏅 Hitos para las cosas de sí o no: Una insignia de hito marca los esfuerzos que simplemente están hechos o no hechos, sin un número que perseguir.
  • ✍️ Los recaudadores registran sus propios números: Tus donantes introducen sus totales desde sus propias páginas, para que el esfuerzo deje de vivir en una hoja de cálculo, un comentario o en ningún sitio.
  • 🤖 Algunos números se cuentan solos: Una etiqueta AUTOMÁTICA aparece donde el sitio ha calculado la cifra a partir de donaciones completadas, para que puedas ver de un vistazo lo que nadie ha escrito.
  • 🧩 Configúralo una vez, úsalo en cualquier lugar: Tú decides qué se cuenta una vez, luego eliges qué campañas lo cuentan. Disponible ahora en Embajadores Benéficos 3.4.7, sin complementos nuevos y sin desarrollador.

Consulta nuestro anuncio aquí.

embajadores Nuevo

🖨️ Presentamos Folletos y Carteles: ¡Recauda fondos fuera de la pantalla!

Gran parte de la recaudación de fondos entre particulares ocurre fuera de la pantalla: en la meta de una carrera de 5 km, en un tablón de anuncios escolar, en la cocina de una oficina. Charitable Ambassadors 3.4.7 añade 2 imprimibles: un folleto de recaudación de fondos que lleva la propia historia y código QR de cada recaudador, y un cartel de reclutamiento que inscribe a nuevos recaudadores. Ambos se abren como una página web normal y se imprimen directamente desde el navegador. Por qué esto es importante:

  • 🏁 Un folleto para cada recaudador: Cada uno lleva la foto, la historia y el objetivo del recaudador, con un código QR que abre su página en lugar de la de tu campaña principal.
  • 📌 Un cartel que recluta: Muestra "Reclutando ahora" encima del nombre de tu campaña con un gran código QR que abre tu formulario de inscripción, para que alguien pueda empezar a recaudar fondos sin esperar un enlace tuyo.
  • 🪄 No se necesita herramienta de diseño: Ambos imprimibles se muestran como una página web normal y se imprimen desde el navegador, sin necesidad de plugin PDF ni diseñador.
  • 📄 2 diseños de folleto: "Repartir" lleva la historia completa para dar a amigos y familiares, y "Colgar" lleva un breve gancho con 5 pestañas para arrancar para un tablón de anuncios.
  • 🛡️ Desactivado hasta que lo actives: Los folletos permanecen desactivados después de la actualización hasta que los habilites en Charitable » Ambassadors » Other » Fliers, y solo el propietario o un administrador puede abrir uno.

Consulta nuestro anuncio aquí.

Mejora Pagos

💸 Presentamos las tarifas escalonadas para el alivio de comisiones: ¡Ajusta la petición a la donación!

El alivio de comisiones hace una pregunta corta a tus donantes al finalizar la compra: ¿te gustaría cubrir la comisión de procesamiento de esta donación? Hasta ahora, esa pregunta utilizaba una única tarifa para cada donación en una pasarela, por lo que una donación de 10 $ y una de 500 $ recibían la misma pregunta de porcentaje. El alivio de comisiones 1.3.0 te permite establecer tantas bandas de donación como desees, cada una con su propia tarifa. Por qué esto es importante:

  • 🪙 Más suave con las donaciones pequeñas: Una comisión de transacción fija supone una parte mucho mayor de una donación de 10 $ que de una de 500 $, por lo que las bandas te permiten pedir menos en la parte inferior.
  • 🎚️ Tantas bandas como necesites: Cada banda tiene su propio porcentaje y su propio importe fijo, y la banda superior continúa sin límite superior.
  • 🛑 Un techo opcional: Un campo de comisión máxima evita que se pida a ningún donante más de una cantidad que tú elijas, por muy grande que sea la donación.
  • 🔌 Configurar por pasarela de pago: Stripe puede funcionar con cuatro bandas, mientras que Windcave y Payfast se mantienen con una tarifa única, ya que las bandas pertenecen a una pasarela y no a todo tu sitio.
  • 🛡️ Nada cambia hasta que tú lo digas: Tus tarifas actuales se mantienen exactamente como están hasta que actives Usar tarifas escalonadas en Charitable » Settings » Advanced » Fee Relief.

Consulta nuestro anuncio aquí.