Donation Router for GiveWP & PayPal Donations
| 开发者 | mralaminahamed |
|---|---|
| 更新时间 | 2026年7月7日 18:46 |
| 捐献地址: | 去捐款 |
| PHP版本: | 8.1 及以上 |
| WordPress版本: | 6.9 |
| 版权: | GPL-2.0-or-later |
| 版权网址: | 版权信息 |
详情介绍:
- Multi-account admin panel — Add and manage any number of PayPal Business accounts under Donation Forms → PayPal Accounts. Each account stores legal entity details (name, tax ID, address, country) alongside AES-256-GCM encrypted API credentials.
- Country routing rules — Define which PayPal account and GiveWP form handles donations from each country. One active rule per country, fully configurable from the admin.
- Country selector popup — A donor-facing modal popup (shortcode
[ador_country_selector]) asks donors to identify their country before proceeding to checkout. Selection is stored in sessionStorage to avoid repeated prompts. - Runtime credential routing — The plugin intercepts GiveWP's IoC container at payment time, substituting the correct PayPal credentials transparently. No GiveWP core files are modified.
- Per-account webhook handling — Each PayPal account receives its own webhook endpoint (
/wp-json/ador/v1/webhook/{account_id}) with independent HMAC signature verification. - Per-entity email tags — Seven GiveWP email template tags populate receipt emails with the correct legal entity name, address, tax ID, tax-deductibility statement, and a unique per-entity receipt number.
- PDF receipts — Optional on-demand PDF receipt download on the GiveWP success page, generated by dompdf.
- Security-first design — AES-256-GCM credential storage, nonce protection, capability checks, webhook signature verification, and
$wpdb->prepare()throughout.
安装:
- Upload the
alamin-donation-routerfolder to the/wp-content/plugins/directory. - Run
composer install --no-dev --optimize-autoloaderinside the plugin directory. - Ensure
AUTH_KEYandSECURE_AUTH_SALTare set to strong, unique values inwp-config.php— these are required for credential encryption. - Activate the plugin through the Plugins screen in WordPress.
- Navigate to Donation Forms → PayPal Accounts and add your first PayPal Business account.
- Configure country routing rules under the Country Routing tab.
- Add the shortcode
[ador_country_selector]to your donation landing page. - Register per-account webhook URLs in your PayPal Developer apps (see the Webhook Setup view for each account).
屏幕截图:
常见问题:
Which payment gateways does this plugin support?
This plugin supports the GiveWP PayPal Donations gateway (also known as PayPal Commerce / PPCP) only. It does not affect or support other GiveWP gateways such as Stripe, Authorize.net, or PayPal Standard.
How many PayPal accounts can I add?
There is no hard limit on the number of PayPal Business accounts you can configure. Each account requires its own PayPal Developer REST app (Client ID and Client Secret) and its own webhook URL registered in PayPal's developer portal.
How are PayPal credentials stored? Is it safe?
Yes. PayPal Client IDs and Client Secrets are never stored in plaintext. They are encrypted with AES-256-GCM using a key derived via HKDF-SHA256 (RFC 5869) from your WordPress AUTH_KEY and SECURE_AUTH_SALT constants (32-byte key). The random nonce and GCM authentication tag are stored alongside the ciphertext as a base64 blob. Credentials are never written to any log. If AUTH_KEY or SECURE_AUTH_SALT are changed, stored credentials become unreadable and must be re-entered.
Can I test with PayPal sandbox accounts before going live?
Yes. The plugin works with both PayPal sandbox and live environments. Add your sandbox accounts the same way as live accounts, using the Client IDs and Secrets from your sandbox REST apps. Register sandbox webhook URLs in PayPal's developer portal using a publicly accessible HTTPS URL (use a tunnelling tool such as ngrok for local development). See operations.md for a full sandbox testing procedure.
What happens if a routing rule is missing for a donor's country?
If no active routing rule exists for the selected country, the credential router falls back to GiveWP's primary PayPal account. The donation is not blocked — it proceeds normally using the default account. An error entry is written to the PHP error log with prefix [ADOR] for the operator's attention.
Does this plugin modify GiveWP core files?
No. The plugin hooks into GiveWP exclusively through WordPress filters, actions, and GiveWP's public IoC container (give()). No GiveWP core files are modified.
Can I use this plugin with GiveWP's built-in email receipts?
Yes. The plugin registers additional GiveWP email template tags that you can insert into your existing GiveWP email templates (GiveWP → Settings → Emails). Tags include {paypal_account_entity_name}, {paypal_account_entity_tax_id}, {paypal_account_receipt_number}, and four others. Tags return an empty string for donations not routed through this plugin, so existing templates work without changes.
The PDF receipt is not generating. What should I check?
Verify that dompdf/dompdf is installed by running composer install in the plugin directory. Confirm that the ador_pdf_receipts_enabled option is set to a truthy value in wp_options. Check the PHP error log for a line beginning [ADOR] PDF receipts disabled: — this will include the underlying error message.
更新日志:
- Per-account live/sandbox environment — manage the same PayPal merchant independently in live and sandbox; routing only applies an account whose mode matches the site's current GiveWP mode.
- Import GiveWP's already-connected PayPal account in one click (reuses stored credentials, no second OAuth).
- Re-sync an imported account's credentials from GiveWP (same-merchant, same-mode guarded).
- Re-activate a deactivated account directly from the Accounts list.
- Delete a PayPal account from the Accounts list (confirmation required; deregisters the account's PayPal webhook first).
- GiveWP version compatibility guard — refuses below GiveWP 3.0 and warns on untested GiveWP majors (
ador_block_on_untested_givewpfilter to fail closed).
- Accounts list gains a Mode column (live/sandbox badge).
- The Import button is always shown on the Accounts list for discoverability — disabled with an inline reason when there is nothing to import (GiveWP not connected, or the account is already imported).
- Flat, minimal admin restyle built on the WordPress core colour palette — status/mode badges, buttons, modals, notices, and the receipt templates. Primary calls to action now use WordPress's native primary-button style.
- Schema 1.1.0: adds the
modecolumn and a compositeUNIQUE(merchant_id, mode)constraint. - Schema now migrates on plugin update, not only on activation.
- List-table bulk actions now reach their handlers. The bulk Apply collided with
WP_List_Table's own action field and dispatched to no handler, dying with an empty error page; the routing field is now printed after the table so it wins. - Refunds to routed accounts no longer fail silently — the PayPal access token is re-minted at refund time instead of reusing the stale connect-time token, and a refund whose account mode does not match the site mode is blocked with an actionable admin error.
- Inbound webhooks for a genuinely unknown account return 404, while a real processing error now logs and returns 500 instead of being masked as not-found.
- Cached PayPal access tokens are encrypted at rest and re-minted on decrypt failure.
- Credential routing no longer fatals against GiveWP's PayPal Commerce contract (overrider parameter-type compatibility).
- Per-account credentials no longer leak to
wp_optionswhen GiveWP refreshes an access token. - Inbound PayPal webhooks read the WP-canonicalised transmission headers, fixing signature verification and dropped events.
- The unused
ador_paypal_modeoption.
- Multi-account admin panel (Donation Forms → PayPal Accounts) with Accounts, Country Routing, and Settings tabs.
- Account add/edit form with AES-256-GCM encrypted credential storage.
- Country routing rules with add/edit/bulk-deactivate actions.
- Custom database tables
{prefix}ador_accountsand{prefix}ador_country_routingwith schema versioning. PayPal_Credential_Routerintercepting GiveWP's IoC container before every PayPal AJAX payment request to substitute per-account credentials.- IoC container rebinding for both
MerchantDetail::classandMerchantDetails::classcovering all GiveWP PayPal credential resolution paths. - Refund routing with inactive-account guard.
- Per-account REST webhook endpoint
POST /wp-json/ador/v1/webhook/{account_id}with HMAC-SHA256 signature verification and idempotency checking. - Country selector popup shortcode
[ador_country_selector]with sessionStorage persistence. - Geolocation hint (non-binding IP-based country pre-selection).
- Seven GiveWP email template tags for per-entity receipt details.
- Per-entity sequential receipt numbers allocated atomically via
FOR UPDATElock. - Default tax-deductibility statement templates for US and Canada.
- PDF receipt generation via dompdf behind
ador_pdf_receipts_enabledoption flag. - Action hooks
ador_credentials_routedandador_webhook_processed. - PHPStan level 8, WPCS 3.x, PHPUnit 9.6 with Brain\Monkey test suite.
- AES-256-GCM encryption for all stored PayPal credentials with HKDF-SHA256 key derivation.
- PayPal HMAC-SHA256 webhook signature verification on all inbound webhook events.
- WordPress nonce protection on all admin form submissions and AJAX endpoints.
current_user_can( 'manage_give_settings' )capability checks on all admin-only actions.$wpdb->prepare()for all parameterised database queries.