Charitable Documentation

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

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!

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!

Donations New

👥 Introducing Donor Merging: Two Records, One Supporter!

Somewhere in your donor list is a supporter who appears twice, because they gave from a work address one year and a personal one the next. Every donation is still recorded and every receipt still went out, but a loyal supporter who has given for years can look like two people who gave half as much. From the Charitable Pro plugin 1.8.19.1 you can find those records and merge them from the Donors screen. Why this is important:

  • 🔍 A Find Duplicates link where you already work: Head to Charitable » Donors and it sits next to Filter and Export, then tells you how many groups of possible duplicates it found.
  • 🧩 Grouped by name, not by email: Charitable compares the first and last name together and ignores capital letters, spacing and punctuation, which is what catches the same person under two different addresses.
  • 📊 A preview before anything changes: Each group shows every record with its email address, its donation count and its lifetime total, and the preview shows you the combined totals and the email that will be added.
  • ↩️ Every merge can be undone: Nothing is merged until you choose to merge it, and you can reverse any merge afterwards, so a wrong guess costs you nothing.
  • 📥 Built for the week after an import: Moving donors over from another plugin is where most duplicates come from, and it is also when they are hardest to spot, because every record is new to you.

Check out our announcement here.

ambassadors New

🔑 Introducing Passwordless Fundraisers: Sign Up With Just an Email!

Supporters arrive wanting to help, and then the form asks them to invent a password for a website they may only visit twice. A lot of them stop right there. Passwordless Fundraiser Accounts, new in Charitable Ambassadors 3.5.0, let a supporter start a peer to peer fundraiser with nothing but an email address. Why this is important:

  • 🔑 No password step to lose them at: Switch it on in Charitable » Ambassadors » Templates » Submit Form and the create-fundraiser form asks only for a name, an email address and a page title.
  • 👤 Still a real WordPress account: One click in one email confirms the address, signs them in and creates the account, so they can come back later to edit their story, change their photo and see who has donated.
  • 🎚️ Your call on every campaign: Each peer to peer campaign can follow the site default or override it, which matters when a campaign pays fundraisers through Stripe Connect and those people do need a password.
  • 📋 See who has not clicked yet: The Charitable » Ambassadors » Directory » Awaiting Sign-In tab lists everyone still waiting, with the campaign they joined and a Resend button, so a typo or a spam folder is something you can spot and fix.
  • 🛡️ Links a scanner cannot use up: Opening the link only shows a page, and your fundraiser is signed in when they press the button on it, so corporate email scanners never burn the link. Each one works once, expires on its own and is stored only as a hash.

Check out our announcement here.

ambassadors New

🏃 Introducing Activity: Show Progress on More Than Money!

Most peer-to-peer fundraisers are about more than the money. A read-a-thon is about minutes read, a walkathon is about miles walked, and a food drive is about meals packed. Activity for Charitable Ambassadors lets your fundraisers show that effort right beside the dollars they raise. Why this is important:

  • 🎯 Progress on what you actually count: A progress bar shows each thing you count against its own target, sitting right beside the money raised.
  • 🏅 Milestones for the yes or no things: A milestone badge marks the efforts that are simply done or not done, with no number to chase.
  • ✍️ Fundraisers log their own numbers: Your supporters enter their totals from their own pages, so the effort stops living in a spreadsheet, a comment, or nowhere at all.
  • 🤖 Some numbers count themselves: An AUTOMATIC tag appears wherever the site worked the figure out from completed donations, so you can see at a glance what nobody typed in.
  • 🧩 Set it up once, use it anywhere: You decide what gets counted one time, then choose which campaigns count it. Available now in Charitable Ambassadors 3.4.7, with no new plugin and no developer.

Check out our announcement here.

ambassadors New

🖨️ Introducing Fliers and Posters: Raise Money Away From the Screen!

A lot of peer-to-peer fundraising happens away from a screen: at the finish line of a 5K, on a school noticeboard, in an office kitchen. Charitable Ambassadors 3.4.7 adds 2 printables, a fundraiser flier carrying each fundraiser’s own story and QR code, and a recruitment poster that signs new fundraisers up. Both open as a normal web page and print straight from the browser. Why this is important:

  • 🏁 A flier for every fundraiser: Each one carries that fundraiser’s own photo, story and goal, with a QR code that opens their page rather than your main campaign.
  • 📌 A poster that recruits: It shows “Now Recruiting” above your campaign name with a large QR code that opens your sign-up form, so someone can start fundraising without waiting on a link from you.
  • 🪄 No design tool needed: Both printables render as a normal web page and print from the browser, with no PDF plugin and no designer.
  • 📄 2 flier layouts: Hand out carries the full story for giving to friends and family, and Post up carries a short hook with 5 tear-off tabs for a noticeboard.
  • 🛡️ Off until you switch it on: Fliers stay off after the update until you enable them under Charitable » Ambassadors » Other » Fliers, and only the owner or an administrator can open one.

Check out our announcement here.

Improvement Payments

💸 Introducing Tiered Rates for Fee Relief: Match the Ask to the Gift!

Fee Relief asks your donors one short question at checkout: would you like to cover the processing fee on this gift? Until now that question used a single rate for every donation on a gateway, so a $10 gift and a $500 gift were asked for the same percentage. Fee Relief 1.3.0 lets you set as many donation bands as you like, each carrying its own rate. Why this is important:

  • 🪙 Gentler on small gifts: A fixed transaction cost is a far bigger share of a $10 donation than a $500 one, so bands let you ask for less at the bottom.
  • 🎚️ As many bands as you need: Each band carries its own percentage and its own fixed amount, and the top band runs on with no upper limit.
  • 🛑 An optional ceiling: A Maximum fee field stops any donor being asked for more than a number you choose, however large the gift.
  • 🔌 Set per payment gateway: Stripe can run on four bands while Windcave and Payfast stay on a single rate, because bands belong to a gateway and not to your whole site.
  • 🛡️ Nothing changes until you say so: Your current rates stay exactly as they are until you switch Use Tiered Rates on under Charitable » Settings » Advanced » Fee Relief.

Check out our announcement here.