Setting up a donation form

Last updated August 5, 2026

Choosing Your Method

There are two primary ways to add a donation form to your site:

  • Puck Page Builder Component: Use this when building or editing pages directly inside the Recur Sites dashboard.

Embeddable Widget: Use this for external websites such as WordPress, Squarespace, or Wix. Important: Using a widget on a Recur Sites page is not supported.

Option 1: Puck Donations Component (Internal Pages)

Use this within the Recur Sites page builder (Puck editor).

How to Add It

  1. Log in to the Recur Sites admin dashboard.

  2. Navigate to the page you want to edit or create a new one.

  3. Open the Page Builder.

  4. In the left component panel, find Donations and drag it onto your page.

Configuration Settings

  • Widget Title: The heading displayed above the form. Default is "Make a Donation".

  • Description: Optional text below the title explaining your mission.

  • Suggested Amounts: Comma-separated dollar amounts for quick-select buttons. Default is "25, 50, 100, 250".

  • Minimum Amount: Smallest donation accepted ($5 default).

  • Maximum Amount: Largest donation accepted ($10,000 default).

  • Allow Recurring: Lets donors choose monthly, quarterly, or yearly schedules (Default: Yes).

  • Default Frequency: The pre-selected option, usually "One-time".

  • Allow Payment Count Limit: Lets donors set a maximum number of payments (Default: Yes).

  • Offer Fee Coverage: Shows an option for donors to cover processing fees (Default: Yes).

  • Processing Fee %: The fee percentage shown to donors (3% default).

  • Button Text: The text on the submit button. Default is "Donate Now".

  • Card Style: Visual style choices include Standard, Minimal, or Elevated (Default).

Option 2: Embeddable Widget (External Sites)

Use this for any website NOT built with Recur Sites.

How to Create and Embed

  1. Go to the Widget Gallery in the Recur Sites dashboard and click + Create Widget.

  2. Select Donations category and Donation Form format.

  3. Configure your settings in the Widget Editor.

  4. Save and return to the Widget Gallery to click the embed code icon (</>).

  5. Copy the code snippet and paste it into a Custom HTML or Code block on your external site (WordPress, Wix, etc.).

Widget Configuration Settings

The widget settings mirror the Puck component but include a few layout options:

  • Widget Name: Internal reference name only.

  • Max Width: Options include Small (400px), Medium (600px), Large (800px), or Full Width.

  • Alignment: Left, Center, or Right.

  • Success Message: The thank-you message shown after a successful donation.

Recur Integration & Stripe Metadata

These settings control how data flows into your reporting and CRM.

Integration Settings

  • Create Contact in Recur: Automatically creates a record in Recur AMS for the donor (Default: Yes).

  • Campaign Name: Associates the donation with a specific campaign for Stripe reporting.

  • Designation: Tags the donation to a specific fund, like "General Fund" or "Scholarship".

  • Appeal Code: A tracking code for specific solicitation efforts (e.g., "EMAIL-SPRING").

  • Donor Group Name: Adds the donor to a specific Recur group. If blank, it defaults to the Campaign Name.

  • Tax Deductibility Statement: Text for the Stripe receipt (e.g., "Tax-deductible to the extent allowed by law").

    Stripe Metadata Keys (For Finance Reporting)

Recur Sites attaches the following metadata to every Stripe transaction:

  • Transaction_type: Always "donation" to filter out other Stripe transactions.

  • Donation_type: Identifies if the gift is "one_time" or "recurring".

  • Campaign_name: Used to filter all revenue attributed to a specific campaign.

  • Designation: The primary field for fund-level reporting and accounting allocation.

  • Appeal_code: Measures the ROI of individual outreach efforts.

  • Frequency: The exact schedule (monthly, quarterly, etc.).

  • Cover_fees: A "true" or "false" value indicating if the donor paid the fee.

  • Fee_amount: The exact fee amount in cents added by the donor.

  • Donor_name / donor_email: Stored as a backup even if the Stripe customer record is incomplete.

Troubleshooting & Best Practices

Best Practices for Reporting

  • Consistency: Use standard fund names for Designations to prevent typos in reports.

  • Time-Bound Efforts: Use Campaign Names for initiatives with start and end dates.

  • Channel Tracking: Use different Appeal Codes for email vs. social media to see which channel performed best.

Common Issues

  • "No Stripe account configured" error: The tenant is missing the Stripe Account ID; contact an administrator.

  • Checkout Fails: Ensure the STRIPE_SECRET_KEY is correctly configured in the environment.

  • Widget returns 503 error: The server may be restarting; wait a moment or check Cloud Run status.

  • Recurring donations not canceling: This usually means the STRIPE_WEBHOOK_SECRET is not set or registered in Stripe.