Charitable Documentation

Learn how to make the most of Charitable with clear, step-by-step instructions.

Popular Resources

Start Here

Donor Management

Recurring Donations

Peer-to-Peer Fundraising

Integrations

Extensions

PayPal Commerce

PayPal Commerce is a single, modern PayPal integration that lets your donors pay with PayPal, Venmo, Pay Later, credit and debit cards, Apple Pay, and Google Pay through one connection. One-click “Connect with PayPal” handles the setup, and donations and refunds flow through the standard Charitable donation admin without needing to log in to PayPal.

Available in Charitable Pro 1.8.15+ and Charitable 1.8.11 (which currently not supporting recurring donations / vaulting).  It has been tested end-to-end on sandbox and live environments, and we will continue refining the experience based on customer feedback.

Key Features

  • Accept donations via PayPal, Venmo, Pay Later, credit and debit cards, Apple Pay, and Google Pay through a single integration.
  • Connect your PayPal business account in one click. No developer needed.
  • Offer one-time donations and recurring donations from the same form.
  • Choose between two recurring modes: PayPal-managed subscriptions, or Charitable-managed renewals using saved payment methods.
  • Let returning donors save their PayPal account or card and reuse it on future donations.
  • Refund and cancel donations directly from the WordPress admin.
  • See real-time PayPal capability status (Payments Receivable, Email Confirmed, Card Processing, Apple Pay, Google Pay, Payment Method Vaulting, Fastlane) in the connection panel.
  • Donors who hit a PayPal-side error see clear, friendly messages with a recovery hint instead of a generic browser alert.

Why Use PayPal Commerce?

PayPal Commerce gives your donors the maximum number of ways to pay without making your team manage multiple gateways. A single connection unlocks PayPal, Venmo, Pay Later financing, full credit and debit card processing through PayPal’s PCI-compliant card fields, and the modern wallets (Apple Pay, Google Pay) all donors expect on a 2026-era donation form. Compared to the older Legacy PayPal integration, you get richer payment options, faster checkout, and admin tooling for refunds and recurring management without ever leaving WordPress.

See It In Action

Requirements

  • Charitable Lite 1.8.11 or Charitable Pro 1.8.15 or later
  • A PayPal business account (you can create one during the connection flow)
  • WordPress 6.0+ and PHP 7.4+
  • The gd or imagick PHP extension if you plan to use receipt PDF generation (already required by Charitable core)

Getting Started

Activation

  1. In your WordPress admin, go to Charitable → Settings → Payment Gateways.
  2. Find PayPal Commerce in the gateway list and click Enable.
  3. Click Settings next to PayPal Commerce, then click the Connect with PayPal button.
  4. PayPal opens in a new window. Sign in to your PayPal business account (or create one) and approve the connection.
  5. PayPal redirects you back to WordPress. The connection panel will show your merchant ID and a checklist of granted capabilities.

That’s it. You can start accepting donations through PayPal Commerce immediately.

Test Mode vs Live Mode

PayPal Commerce respects Charitable’s standard Test Mode toggle. With Test Mode on, donations route through PayPal’s sandbox so you can validate the full donor flow without moving real money. Switch Test Mode off when you’re ready to accept live donations.

Saved payment methods are scoped per merchant: a card you saved in sandbox will not appear in live mode, and vice versa.

Configuration Options

After connecting, the PayPal Commerce Settings page exposes these options. Most defaults are sensible for a new installation, so you can typically leave them alone.

Payment Methods

SettingTypeDefaultDescription
Enable VenmoToggleOffShow the Venmo Donate button alongside PayPal. Venmo is US-only and requires the Pay Later capability on your PayPal account.
Enable Pay LaterToggleOffShow PayPal’s Pay Later button (Pay in 4, PayPal Credit). Eligibility is determined by PayPal at checkout based on the donor’s region and the donation amount.
Enable Card Fields (ACDC)ToggleOnRender PayPal’s PCI-compliant credit and debit card fields directly on your donation form. Falls back to a standalone “Debit or Credit Card” button if PayPal hasn’t enabled Card Fields on your account yet.
Enable Apple PayToggleOnShow the Apple Pay button on Safari. Requires Apple Pay capability on your PayPal account.
Enable Google PayToggleOnShow the Google Pay button on Chrome. Requires Google Pay capability on your PayPal account.
Enable FastlaneToggleOnAllow returning donors to check out with Fastlane (PayPal’s saved-checkout option for guests).
Fastlane BehaviorSelectGuests OnlyChoose when Fastlane is offered: guests only, all donors, or never.

Saved Payment Methods (Vaulting)

SettingTypeDefaultDescription
Enable Payment Method VaultingToggleOnAllow donors to save PayPal accounts and cards on the donation form for use on future donations.
Vaulting Option DisplaySelectOpt-inChoose how the “Save my payment method” option appears at checkout: opt-in (unchecked by default), opt-out (checked by default), or always save.
Vaulted Method Expiry (Days)Number(empty)Number of days before unused saved methods are automatically expired. Leave empty for no expiration.

Recurring Donations

SettingTypeDefaultDescription
Auto-vault for Recurring DonationsToggleOnAutomatically save the donor’s payment method when they choose a recurring donation. Required for the renewal cron to charge later cycles.
Recurring Processing ModeRadioPayPal Subscriptions APIChoose how recurring donations are processed. Vault + Cron: your site stores the payment token and triggers each renewal. PayPal Subscriptions API: PayPal manages the renewal cycle automatically (requires Pro license; Lite sites automatically fall back to Vault + Cron with a small platform fee on each renewal).

Recurring Mode Deep Dive

PayPal Commerce supports two distinct ways to handle recurring donations. Both work with the same donor experience, but the behind-the-scenes flow differs.

Vault + Cron (Merchant-managed)

When a donor chooses a recurring donation, your site saves their PayPal account or card as a vaulted token. On every cycle, Charitable’s cron triggers a fresh charge against that token through PayPal’s Orders API. You retain full control over retry behavior, dunning, and cancellations through Charitable’s recurring donations admin.

Works on Lite and Pro. Lite sites pay a small platform fee (3%) on each renewal capture; Pro sites pay no platform fee.

PayPal Subscriptions API (PayPal-managed)

When a donor chooses a recurring donation, your site creates a PayPal billing plan and a subscription. PayPal handles the renewal cycle automatically and notifies your site when each cycle bills. Donors can also see and manage the subscription in their own PayPal account.

Available on Pro only. Lite sites that select this mode automatically fall back to Vault + Cron, so donors never see an error.

Pro Activation on Existing Recurring Donations

If you activate Pro on a site that already has Lite recurring donations in flight, the platform fee is automatically dropped on the next renewal. You do not need to migrate the subscription, prompt the donor to re-approve, or take any other action. The fee gate is checked at every renewal based on your current license state.

Refunds and Cancellations

Refunds and cancellations are issued from the standard Charitable donation admin. You don’t need to log in to PayPal.

Refund a Donation

  1. Open the donation in Charitable → Donations.
  2. In Donation Actions, choose Refunded and check “Refund in PayPal Commerce automatically.”.
  3. Click Update Status.

If the refund succeeds, the donation status moves to Refunded and the refund ID is recorded in the donation log. If the refund fails (for example, PayPal returns “insufficient balance”), the donation status is reverted to Paid so your records and PayPal stay in sync.

Cancel a Recurring Donation

  1. Open the recurring donation in Charitable → Recurring Donations.
  2. In Donation Actions, choose Cancel in Gateway.
  3. Click Cancel Recurring Donation.

The cancellation is sent to PayPal so the donor isn’t billed again, and the recurring donation post is set to Cancelled in WordPress.

Donor-Facing Errors

When PayPal can’t process a donation (the merchant account is restricted, the card is declined, the country isn’t supported, etc.), donors see a plain-language inline notice on the donation form with a recovery hint. They never see a generic browser alert dialog.

Examples:

  • “Online donations via PayPal are temporarily unavailable. Please try a different payment method, or contact us to complete your donation.”
  • “Your payment method was declined. Please try a different card or use PayPal balance.”
  • “Donations via PayPal are not supported from your country. Please try a different payment method.”

If the current visitor is signed in as an admin (capability manage_charitable_settings or manage_options), the inline notice additionally shows the underlying PayPal error text and the PayPal debug ID so you can triage without checking the logs.

Logs

Every PayPal API error is recorded in Charitable → Tools → Logs under the source paypal_commerce. Each entry includes:

  • The friendly message the donor was shown
  • The raw PayPal error text
  • PayPal’s error issue code (e.g., PAYEE_ACCOUNT_RESTRICTED)
  • PayPal’s debug ID (for support tickets with PayPal)
  • Donation context: amount, campaign, payment method

This is the fastest way to diagnose a customer report of “PayPal isn’t working.”

Troubleshooting

Donors see “Online donations via PayPal are temporarily unavailable.”

This message indicates PayPal has restricted your merchant account. Sign in to paypal.com with your business account, address any pending verification or compliance items, and then return to Charitable → Settings → Payment Gateways → PayPal Commerce and click Refresh Status to confirm the restriction is cleared.

The “Pay with Card” tab doesn’t render; only a “Debit or Credit Card” button shows.

PayPal hasn’t yet enabled the Advanced Card Processing (ACDC) capability on your account. The standalone Card button still accepts donations through a hosted PayPal popup. To enable inline card fields, log in to your PayPal business account, complete any pending verification steps, and return to the connection panel and click Refresh Status.

After disconnecting and reconnecting, the connection still shows the old merchant.

Clear your WordPress object cache (or restart your PHP-FPM service if a host-level cache is involved). The Refresh Status button forces a fresh capability check from PayPal.

Recurring donations never renew.

Check that Auto-vault for Recurring Donations is on and that WordPress cron is running on your server. For Vault + Cron mode, the renewal cron fires daily and charges each due recurring donation. Look in Charitable → Tools → Logs for entries from paypal_commerce to see if any renewal attempts have run or failed.

Refund button shows “No capture ID found” on a subscription donation.

This can happen if you attempt a refund within seconds of the donor approving the subscription, before PayPal has recorded the first transaction. Wait a few minutes and try again. The plugin will recover the capture ID from PayPal’s transaction history at refund time.

Developer Resources

Hooks & Filters

  • charitable_paypal_log_platform_fee_on_donation (filter, default false). Return true to append a “Platform fee” line to the donation log on every capture. Useful for sites that want full visibility into Lite-tier renewal fees.
  • charitable_paypal_platform_fee_percentage (filter, default 3). Adjust the platform fee percentage applied to Lite-tier donations.
  • charitable_donation_cancellation_page (filter). Customize the page donors land on after cancelling a PayPal subscription approval.
  • charitable_donation_cancellation_args (filter). Customize the query args appended to the donation cancellation URL.

WP-CLI

The plugin ships with one PayPal-specific WP-CLI command:

wp charitable paypal force-commerce-tier

Use this if Charitable detected your site as a Legacy PayPal site (e.g., it has imported donations from a legacy export, or an abandoned legacy gateway test) and you want to opt in to PayPal Commerce instead. Includes a --dry-run preview, and a required --confirm-recurring-impact acknowledgement when active legacy recurring donations are present.

Webhooks

Once you connect, the connection panel exposes your site’s webhook URL. Subscribe to these events in your PayPal Developer Dashboard:

  • CHECKOUT.ORDER.APPROVED
  • PAYMENT.CAPTURE.COMPLETED
  • PAYMENT.CAPTURE.DENIED
  • PAYMENT.CAPTURE.PENDING
  • PAYMENT.CAPTURE.REFUNDED
  • MERCHANT.ONBOARDING.COMPLETED
  • MERCHANT.PARTNER-CONSENT.REVOKED

For sandbox accounts you can also click Auto-Create Webhook to register them automatically.

Additional Resources

Still have questions? We’re here to help!

Submit a Support Ticket
Contact Us

Last Modified:

What's New In Charitable

View The Latest Updates
🔔 Subscribe to get our latest updates
📧 Subscribe to Emails

Email Subscription

Join our Newsletter

We won’t spam you. We only send an email when we think it will genuinely help you. Unsubscribe at any time!

GiveWP Migrations New

White Glove Migration Service for GiveWP

Thinking about switching your fundraising platform from GiveWP to Charitable, but don’t want to risk losing your data or handle a complex technical setup yourself? Charitable’s White Glove Migration Service features:

👥 Flawless Donor Mapping: Safely transfer your entire supporter database with zero data loss.

📊 Complete Financial History: Meticulously preserve every historical transaction for continuous, accurate reporting.

🔄 Seamless Recurring Giving: Safely transfer active sustaining subscriptions without disrupting your incoming revenue or requiring your donors to update their information.

💳 Zero Gateway Disruptions: Keep using Stripe, PayPal, or any other GiveWP-compatible processor you already love.

🚀 Expert Technical Setup: Relax while our team handles the heavy lifting to install and configure your forms—plus, qualifying users get a full year of Charitable Pro completely free.

Visit this page to learn more.

automation Improvement

📢 New Feature Alert: Automation Connect 2.0 Is Here! 🚀

Thinking about connecting your fundraising data to tools like Mailchimp, Slack, or Google Sheets, but don’t want to hire a developer or write custom code? Charitalbe’s new automation addon has:

⚡ 17 Event Triggers: Instantly fire webhooks for a donor’s first gift, renewal payments, or reached campaign milestones.

🎯 Smart Conditional Logic: Use powerful AND/OR logic across 11 fields to only send data when it meets your exact criteria, like newsletter opt-ins.

📊 Custom Payload Control: Select from 80+ clean data fields across donor, donation, and campaign metadata so your apps get exactly what they need.

🚀 Pre-Built Platform Templates: Skip the setup from scratch with ready-to-go templates for Zapier, Make.com, n8n, HubSpot, and Slack.

🛡️ Reliable Developer Tools: Power your workflows with signed HMAC-SHA256 payloads, complete WordPress filters, and automatic retry logs.

automation Improvement

🔌 Charitable Meets Zapier: Connect to 7,000+ Apps and Automate Your Fundraising

Tired of manually copying donation data into accounting sheets or tracking down new donor signups? Put your administrative tasks on autopilot. Charitable is now officially on Zapier, giving you a powerful, no-code way to plug your fundraising directly into the rest of your favorite tools.

Every donation, donor signup, and campaign milestone can now trigger an automated workflow seamlessly.

What’s New:

♾️ Connect to 7,000+ Apps: Bridge your Charitable campaigns with everyday software like Google Sheets, QuickBooks, Slack, Mailchimp, HubSpot, Notion, Airtable, and thousands more.

⚡ 12 Powerful Triggers: Build deep workflows using smart automation triggers covering the entire donation lifecycle—including New Donation, New Donor, Subscription Cancelled, and Campaign Goal Reached.

📋 Pre-Built Action Templates: Get started in three minutes or less with our pre-made template combinations, like automatically logging new donations straight into a Google Sheet or firing custom donor welcome emails through Gmail.

🚫 Zero Code Needed: No complex webhooks or custom PHP scripts required. Just pick your trigger, choose your app, map your fields, and let Zapier handle the heavy lifting.

Ready to save hours of admin time? Grab Charitable Pro with the Automation Connect addon today and launch your first Zap!

Improvement Payments

🚀 Introducing PayPal Commerce: One Connection, Six Ways to Donate

Donors expect modern, flexible payment options when they support a cause. If they don’t see their preferred method on your donation form, they often disappear without a word. With PayPal Commerce, we are bringing a completely modernized checkout experience right to your campaigns.

Enjoy a single integration that upgrades your forms, makes giving seamless, and helps you capture every single donation.

What’s New:

🔌 One-Click Connection: Skip messy API keys and developer docs. Simply click “Connect with PayPal,” sign in to your business account, and your modern form is live in under five minutes.

💳 Six Ways to Give: Give your supporters instant access to PayPal balance, Venmo (US), Pay Later financing, major credit/debit cards, Apple Pay (Safari), and Google Pay (Chrome) all from the exact same form.

🔄 Flexible Recurring Giving: Fully supports monthly giving. Choose between the PayPal Subscriptions API (handled automatically on PayPal’s end) or Vault + Cron (handled securely right on your site).

💬 Friendly Error Recovery: No more confusing browser alerts. If a payment is declined, donors see plain-language, inline messages that guide them on how to fix the issue and complete their gift.

Ready for PayPal, modernized? Update to Charitable Pro 1.8.15+ (or Charitable Lite 1.8.11+) and connect your account today!

Campaigns New

⏳ Campaign Countdown: Drive Urgency and Lift Donations

Urgency is one of the most powerful tools in fundraising! Meet Campaign Countdown—a live, real-time timer built to turn procrastination into immediate generosity.

campaign_countdown_animation

What’s New:

⏱️ Live, Real-Time Urgency: Beautifully track days, hours, minutes, and seconds down to your campaign’s deadline w/ live-updating visual countdowns.

🎨 Tailored to Your Look: Choose between Boxed bordered tiles or a clean, single-line Inline display. Match your theme instantly with font and deep color controls.

🛠️ Place it Anywhere: Drop the countdown anywhere you like using the Campaign Builder field, a dedicated Gutenberg block, or a simple shortcode.

🚨 Smart Expiry Actions: Total control over the end state—choose to automatically replace the timer with a custom message, freeze it at zero, and more.

View All Announcements