PCO Pledge Form

Collect public pledge submissions, match people in Planning Center, and create or review Planning Center Giving pledges.

Requirements

• WordPress 5.8 or later
• PHP 7.4 or later
• A Planning Center account with access to People and Giving
• A Planning Center Personal Access Token with an App ID and App Secret

Tested with WordPress 7.0. Current stable version: 0.4.0.

Licensed under GPLv2 or later.

Description

PCO Pledge Form adds a responsive pledge modal and a standalone pledge page to a WordPress site. It loads pledge campaigns from Planning Center Online, calculates the full pledge from the selected frequency, and stores each submission locally while it is confirmed, synchronized, or reviewed.

Features:

• Displays available Planning Center pledge campaigns.
• Caches the Planning Center campaign list for ten minutes.
• Accepts one-time, monthly, and weekly pledge frequencies and calculates the total pledge.
• Opens from any same-site link that points to #pledge-modal or /pledge-modal/.
• Automatically matches only when a submitted phone number uniquely identifies one Planning Center person.
• Emails a secure, single-use confirmation link to the matched person's primary Planning Center email address.
• Automatically creates or updates a matched Planning Center Giving pledge only after explicit email confirmation.
• Lets a pledger confirm whether to replace or add to an existing pledge.
• Holds unmatched submissions for administrator review.
• Provides an administrator search, match, and sync workflow under PCO Pledges.
• Uses nonces, a honeypot, minimum completion time, and rate limits to reduce automated abuse.
• Supports a configurable three-letter currency code.

This plugin connects to the Planning Center API. Submitted names, phone numbers, campaign identifiers, person identifiers, and pledge amounts may be sent to Planning Center as part of the requested service.

Installation

1. Confirm the plugin folder is named pco-pledge-form and that pco-pledge-form.php is directly inside it.
2. Create a ZIP file whose top-level folder is pco-pledge-form, rather than a ZIP that opens directly to loose plugin files.
3. In WordPress, go to Plugins > Add New Plugin > Upload Plugin.
4. Select the ZIP file, choose Install Now, and then choose Activate Plugin.
5. Confirm that PCO Pledges appears in the WordPress administrator menu, then go to PCO Pledges > Settings.
6. Enter the App ID and App Secret from a Planning Center Personal Access Token that can search People and manage Giving pledges.
7. Enter a three-letter currency code such as USD, then save the settings.
8. Add a menu item, button, or link that points to #pledge-modal. You can also link to https://example.org/pledge-modal/, replacing example.org with the site domain.

The App Secret field appears blank after it is saved. Leave it blank on a later save to keep the stored secret.

Credentials can also be defined in wp-config.php with PCO_PLEDGE_APP_ID and PCO_PLEDGE_APP_SECRET. The optional PCO_PLEDGE_CURRENCY constant sets the currency code. These constants take precedence over settings saved in WordPress and can keep the secret out of the WordPress options table; protect wp-config.php and site backups accordingly.

Using the Form

The recommended presentation is a Custom Link, button, or linked text whose URL is exactly #pledge-modal. The plugin recognizes that fragment on any page and opens the form over the current page. A direct visit to /pledge-modal/ displays the standalone form.

For each submission:

1. The visitor enters an amount, selects a live Planning Center campaign, and chooses Once, Monthly, or Weekly. The full pledge is calculated as the amount multiplied by 1, 12, or 52, respectively.
2. The visitor enters a first name, last name, and phone number.
3. The plugin searches Planning Center by phone number. Only one unique phone-number match is accepted automatically.
4. If the person already has a pledge for the campaign, the visitor chooses whether to replace it with the new total, add the new total, or stop without making a change.
5. For a uniquely matched person, the plugin emails a single-use confirmation link to the primary, unblocked email address in Planning Center. The visitor must review the request and explicitly confirm it before the plugin writes to Planning Center.
6. Unmatched submissions, missing email addresses, email delivery failures, and synchronization failures are sent to the administrator review queue.

After setup or an update, test the form in a private or staging window after clearing page, CDN, and browser caches. Confirm that campaigns load, the confirmation email arrives, and a test pledge reaches the expected Planning Center campaign only after confirmation.

Administrator Review

Go to PCO Pledges in the WordPress administrator menu to review Pending or Error submissions. The screen includes the pledger, campaign, total, status, submission time, and any recorded error.

To resolve a submission, search Planning Center by name or phone number, select the correct person, choose whether an existing pledge should be replaced or increased, and select Link & Sync. Successfully synchronized submissions leave the review list; automatically confirmed pledges do not appear there.

Frequently Asked Questions

What happens when the plugin cannot find exactly one person?

The submission is stored as pending. An administrator can open PCO Pledges, search Planning Center by name or phone number, select the correct person, and choose Link & Sync.

What happens when a pledge already exists for the campaign?

The pledger can choose to replace the existing total, add the submitted total to it, or stop without making a change. A replace or add request is applied only after the pledger confirms it through the primary email address stored in Planning Center.

What happens if the person has no usable Planning Center email address?

The pledge remains pending for administrator review. The same fallback applies if the confirmation email cannot be sent or the Planning Center sync fails. An unconfirmed pledge that expires is closed without changing Planning Center.

How are confirmation emails sent?

The plugin uses the WordPress wp_mail() function. Configure authenticated SMTP or a transactional email provider for reliable delivery.

Does deleting the plugin remove its local data?

Yes. Deleting the plugin through WordPress removes the plugin settings and its local pledge table. Pledges already created in Planning Center remain in Planning Center.

Deactivating the plugin does not remove its settings or local pledge records.

Privacy

The plugin stores the submitted name, phone number, campaign, amount, frequency, total, status, Planning Center identifiers, error details, timestamps, and cryptographic hashes of the email address, confirmation token, IP address, and browser user agent in a custom WordPress database table. It sends data needed to search for a person and create or update a pledge to Planning Center, and sends a confirmation email before a matched pledge is written. Site administrators determine retention practices for both systems.

After activation, review Settings > Privacy in WordPress and add or adapt the plugin's suggested text in the site's published privacy policy. Establish an organizational retention policy for pending and error submissions.

Security Notes

• Use a dedicated Planning Center user or token with only the access needed for People searches and Giving pledges.
• Protect wp-config.php, WordPress database backups, and administrator accounts because they may contain credentials or pledge information.
• Use HTTPS and keep WordPress, this plugin, the active theme, and other plugins updated.
• Configure authenticated SMTP or a transactional email provider and monitor delivery so confirmation messages reliably reach pledgers.

Troubleshooting

• Campaigns unavailable: Recheck the App ID and App Secret, confirm that the Planning Center token can access Giving, save the settings again, and allow up to ten minutes for the campaign cache to refresh.
• The link does not open the form: Use exactly #pledge-modal or the site's /pledge-modal/ URL, then clear page, CDN, and browser caches.
• The form reports an invalid submission: Reload the page to obtain a fresh security token and try again.
• A submission is missing from the review list: Automatically confirmed and synchronized pledges leave the list. Check Planning Center Giving for the pledge.
• A person is not matched automatically: Confirm that the submitted phone number matches Planning Center, then use the administrator review workflow to search for and link the correct person.
• A confirmation email does not arrive: Confirm the person's primary Planning Center email is usable, check the site's mail logs, and verify the WordPress SMTP or transactional email configuration.