Donaciones recurrentes

Una donación recurrente es una instrucción guardada para cobrar la tarjeta de un donador en un horario — típicamente semanal, quincenal o mensual. La tarjeta es tokenizada por nuestro gateway así que nunca manejas un PAN real. Una vez configurada, los cargos suceden automáticamente mediante un trabajo cron diario.

Dos vías para configurar

Vía	Quién la inicia	Cuándo usar
Iniciada por admin	Un miembro del personal, usando los detalles de la tarjeta del donador	El donador te dijo en persona y estás ingresando en su nombre
Iniciada por visitante	El donador, en el formulario público de donación	El donador quiere autoservirse desde casa

Ambas vías producen la misma fila de base de datos en recurring_donations y son procesadas por el mismo trabajo nocturno.

Configuración iniciada por admin

1. Abre el perfil de miembro del donador → pestaña Donaciones.
2. Haz clic en la acción de crear recurrente.
3. Llena:
   • Fondo — a qué categoría va cada cargo.
   • Monto — monto por cargo.
   • Frecuencia — semanal, quincenal, mensual.
   • Fecha de inicio — cuándo se ejecuta el primer cargo.
   • Fecha final (opcional) — déjala en blanco para indefinido.
   • Detalles de tarjeta — número, expiración, CVV. Estos pasan a nuestro gateway y regresan como un token.
4. Guarda.

El primer cargo usualmente se ejecuta inmediatamente (o en la fecha de inicio si está en el futuro). Los cargos subsecuentes se ejecutan cada noche hasta que la programación diga que no deberían.

La función edge que potencia esto es create-recurring-donation-gc — tokeniza la tarjeta vía PowerTranz, almacena solo el token + últimos cuatro dígitos + expiración en la base de datos, y nunca toca el PAN completo más allá del envío inicial.

Configuración iniciada por visitante

Cuando un donador visita tu formulario de donación público y selecciona Hacer esta una donación recurrente, el formulario cambia al modo recurrente:

1. El donador elige frecuencia, monto, fondo, fecha de inicio.
2. Los detalles de tarjeta del donador pasan por un flujo de checkout hospedado (Genius Checkout) — ingresa la tarjeta en una página hospedada por el gateway, no por GCM.
3. El gateway devuelve un token.
4. La función edge start-public-recurring-donation-gc guarda la fila de donación recurrente usando ese token.

El donador recibe un correo de confirmación y puede administrar (cancelar, cambiar monto) la donación recurrente iniciando sesión en su cuenta de miembro o haciendo clic en un enlace mágico en el correo de confirmación.

Requisito de tarjeta archivada

Para cobrar más tarde sin el donador presente, la tarjeta debe ser tokenizada en la configuración. Algunos métodos de pago no pueden ser tokenizados — por ejemplo, ciertas tarjetas de débito en algunas regiones. El flujo de configuración muestra un error "esta tarjeta no se puede usar para recurrentes" en ese caso; el donador debería cambiar a una tarjeta diferente.

Trabajo nocturno de cobro

La función edge charge-recurring-donations se ejecuta una vez al día. Para cada donación recurrente cuya next_charge_date ha llegado:

1. Llama al gateway con el token guardado y el monto.
2. Si el cargo tiene éxito — escribe una fila de donación, avanza next_charge_date a la siguiente fecha programada.
3. Si el cargo falla — registra el fallo, envía al donador un correo pidiéndole que actualice su tarjeta, y reintenta en la siguiente ejecución nocturna por hasta 5 días. Después de 5 fallos, la donación recurrente se pausa.

INFO

Deliberadamente reintentamos en lugar de pausar inmediatamente — los rechazos del banco son a menudo transitorios (fondos insuficientes momentáneamente) y se resuelven solos en un día.

Vista del donador

Los donadores pueden:

• Ver sus donaciones recurrentes activas en el perfil de miembro (si han iniciado sesión).
• Verlas en el enlace Administra tus donaciones del correo de confirmación.
• Cancelar desde cualquier lugar — la cancelación es inmediata.
• Cambiar el monto o frecuencia — produce una nueva fila recurrente y termina la antigua.

Vista de admin

La página Donaciones → Recurrentes lista cada donación recurrente en el espacio de trabajo. Puedes:

• Filtrar por donador, fondo, estado.
• Ver la última fecha de cargo y próxima fecha de cargo de cada recurrente.
• Pausar / reanudar programaciones individuales.
• Cancelar en nombre del donador.

Cancelación

Una donación recurrente puede ser cancelada por:

• El donador (desde el enlace de administración).
• Un admin (desde la página de donaciones recurrentes).
• El sistema, después de 5 cargos fallidos consecutivos.

Cancelar no reembolsa cargos previos. Las donaciones pasadas permanecen en el perfil del donador y en los estados de cuenta de fin de año.

Permisos

Acción	Admin	Tesorero	Donador (propio)
Crear recurrente	sí	sí	sí
Ver lista de recurrentes	sí	sí	solo propias
Editar monto / frecuencia	sí	sí	solo propias
Cancelar	sí	sí	solo propias

Preguntas comunes

¿Qué pasa si la tarjeta expira? El donador recibe un correo una semana antes de la expiración pidiéndole que actualice. Si no lo hace, el siguiente cargo falla y comenzamos el ciclo de reintentos.

¿Puedo reembolsar un cargo recurrente? Sí — abre la fila de donación y haz clic en reembolso. Llamamos a process-refund contra el gateway. Los reembolsos aparecen como una donación negativa en los estados de cuenta de fin de año.

¿Las programaciones recurrentes son conscientes de la zona horaria? Sí. Cobramos basados en la zona horaria de tu iglesia (configurada en Configuración → Organización), no en UTC.

Próximos pasos

• Formulario de donación en línea — donde los visitantes se autosirven.
• Estados y recibos — vista de fin de año de donaciones recurrentes.
• Lanzar una campaña de donaciones — receta que usa donaciones recurrentes.