Overview

Fundorex supports monthly donations in two modes:

• Native auto-charge (Stripe + Razorpay): a Monthly checkout creates a real subscription at the gateway. Renewals charge automatically and webhooks keep each donation record in sync (renewals, failures, pause/resume/cancel).
• Reminder flow (all other gateways): the donor gets a monthly "pay again" reminder email instead of an automatic charge.

Native recurring works in every donation flow: the main donation checkout, embed donations, Fundraising plugin pledges (Once/Monthly toggle), and community fundraising contributions.

Donor experience

1. On the donation/pledge form the donor picks Monthly instead of Once.
2. With Stripe or Razorpay, checkout creates a gateway subscription (monthly interval). The first payment completes the donation immediately.
3. Renewals charge automatically each month. No further action is needed from the donor.
4. With any other gateway, Monthly records a recurring entry and the donor receives a reminder each month to pay again.
5. Donors can cancel a recurring donation from the user dashboard. Canceling also cancels the subscription at Stripe/Razorpay, so no further charges occur.

Admin setup

1. Enable the gateway and monthly option

1. Go to General Settings > Payment Gateway and configure Stripe and/or Razorpay with live (or test) API keys.
2. Fill in the new fields:
   • Stripe Webhook Secret — signing secret from the Stripe webhook endpoint.
   • Razorpay Webhook Secret — secret from the Razorpay webhook.
   • Stripe Connect Account ID (optional) — your acct_xxx Express account id, only needed for split payouts.
3. Use test keys + test mode first, run a monthly checkout, and confirm the subscription row flips to active.

2. Register webhook URLs

Each gateway's settings panel shows its exact callback URLs under the webhook/setup section. Register them in the gateway dashboard:

• Stripe: Developers > Webhooks > add the donations recurring webhook URL. Enable invoice.payment_succeeded, invoice.payment_failed, customer.subscription.deleted. Copy the signing secret into Stripe Webhook Secret.
• Razorpay: Settings > Webhooks > add the donations recurring webhook URL. Enable subscription.charged, subscription.cancelled, subscription.paused, subscription.resumed. Copy the secret into Razorpay Webhook Secret.

The same settings panel documents the other supported gateways (Paystack, Flutterwave, Mollie, PayPal, Cashfree, Midtrans, Xendit, Mercado Pago, Payfast, Square, Authorize.Net, PayTabs, Paytm, Senangpay) with the events to enable and badges showing whether each one is natively auto-recurring, package-ready, or one-time-only. Donation checkout in this app currently offers Monthly on Stripe/Razorpay.

3. Environment keys

The following keys must exist in your .env (see env-sample.txt):

RAZORPAY_WEBHOOK_SECRET=
STRIPE_WEBHOOK_SECRET=
STRIPE_CONNECT_ACCOUNT_ID=

Requires xgenious/paymentgateway v5.1 or newer (recurring + connect APIs).

4. Cron (reminder flow + finalization)

Native Stripe/Razorpay renewals are driven by webhooks, but the scheduler is still required:

• donation:recurring — sends monthly reminders for non-native recurring donations (automatically skips active Stripe/Razorpay subscriptions, so native donors never get duplicate reminders).
• fundraising:finalize-campaigns — finalizes Fundraising plugin campaigns past deadline.

Add both to the scheduler; see Cron Job for cPanel/SiteGround setup.

How renewals and failures are recorded

• Successful renewal webhooks extend the recurring record and log the payment.
• Failed payments are recorded with a failed status so admin can follow up.
• Pause/resume/cancel events from the gateway update the subscription status (pending, active, paused, cancelled).
• Dashboard cancel calls the gateway cancel API first, then marks the local record cancelled. If the gateway call fails, the failure is logged and the local state is left unchanged for retry.

Fundraising pledges and community contributions

• Fundraising campaign pledge forms include the same Once/Monthly toggle. Monthly + Stripe/Razorpay creates a subscription pledge; other gateways stay one-time.
• Community fundraising contributions follow the same rule: native auto-charge on Stripe/Razorpay, reminder flow otherwise.

Troubleshooting

• Subscription stuck at pending: the webhook never arrived. Check the webhook URL is registered, events are enabled, and the webhook secret matches the value in settings.
• Donor got a reminder for a Stripe/Razorpay monthly: upgrade to the release containing the donation:recurring skip for active native subscriptions, and confirm the pledge shows subscription_status = active.
• Cancel did not stop charges: check the gateway dashboard — if the subscription is still active there, re-run cancel from the user dashboard and check the log for gateway API errors.
• Monthly option missing at checkout: it is only offered for Stripe/Razorpay in the current checkout. Other gateways show one-time only.