Donation Router for GiveWP & PayPal – Route Donations by Donor Country

FAQ

Do I need a PayPal Developer app for every account?

No. Connect with PayPal on the Add Account screen onboards a PayPal Business account through GiveWP’s own approved partner, so no separate PayPal app or client secret is needed. If GiveWP is already connected to a PayPal account, Import from GiveWP adopts it without a second authorisation. Manual entry of a Client ID and Secret remains available.

Does this work with recurring donations?

Not yet — and this matters if you sell them. GiveWP’s PayPal Commerce gateway supports subscriptions via the paid Recurring Donations add-on, which creates a PayPal billing plan through its own code path. This plugin routes credentials on the one-time donation path only, so with that add-on active a recurring donation’s plan is created under GiveWP’s default PayPal account rather than the account for the donor’s country. Renewals then bill at PayPal against that plan, so nothing later can redirect them. One-time donations route correctly. If you need per-country routing for recurring gifts, treat it as unsupported for now.

All my donations are going to the wrong PayPal account. Why?

Almost always an environment mismatch. Every account here is either live or sandbox, and routing only applies an account whose environment matches GiveWP’s current mode. If GiveWP is in test mode and your accounts are live — or the reverse — every account is skipped and the donation falls through to GiveWP’s own default PayPal account. The account still shows as Active, because it is; it is just unusable in that mode.

The readiness panel on the Accounts screen reports this directly. The other causes it detects are a country with no active routing rule, a rule pointing at an account that was deactivated afterwards, and a rule whose donation form was deleted or unpublished. All four produce the same symptom: the money quietly reaches the default account.

My country has no tax-deductibility statement. What do I do?

Write your own. The plugin ships default statement text for the United States (501(c)(3)) and Canada (CRA) only; every other country starts blank, because the correct wording is jurisdiction-specific and getting it wrong is a compliance problem rather than a formatting one.

Edit an account and fill in its Tax-Deductibility Statement, using the email tags listed beneath the field to pull in that entity’s name, tax ID and receipt number. Have a qualified tax or legal adviser approve the wording for each entity before you take live donations, then tick the legal-review acknowledgement under Settings. That acknowledgement is a reminder for your own records — the plugin does not block donations while it is unticked.

Can one PayPal account receive donations from several countries?

Yes. The constraint is one active rule per country, not per account — the country_code column carries a unique key. Point as many countries as you like at the same account. A single European entity serving a dozen countries is a normal setup.

What happens if I change AUTH_KEY or SECURE_AUTH_SALT?

Every stored PayPal credential becomes permanently unreadable. The encryption key is derived from those two constants, so rotating either one means the ciphertext can no longer be decrypted — there is no recovery path, and you must re-enter or re-connect each account.

The Accounts screen detects this and tells you what happened rather than failing obscurely. If you plan to rotate salts, have your credentials to hand first, or re-run Connect with PayPal for each account afterwards.

How do refunds work?

Refund a donation the normal GiveWP way and the plugin routes the refund back through the account that originally took the payment, using the account recorded on that donation rather than whichever account is currently default.

Two situations stop a refund with an explanatory message instead of failing at PayPal: the original account has since been deactivated (reactivate it first), or that account’s environment no longer matches GiveWP’s current mode (switch GiveWP to that mode first). Both are deliberate — the alternative is an opaque authentication error from PayPal.

What happens if I deactivate or delete an account that still has routing rules?

Deactivating an account leaves the rules pointing at it untouched, and donations for those countries fall through to GiveWP’s default PayPal account. The readiness panel flags this specific situation, since nothing else about the admin would show it. Repoint or deactivate the affected rules as well.

Deleting an account asks for confirmation and deregisters its webhook at PayPal first. Donations already processed keep their record of which account handled them, so past receipts remain correct.

Is geolocation required? What does it actually do?

No, it is optional and off unless you enable it. When on, it pre-selects a country in the selector modal as a hint — the donor’s own choice always wins, and no country is ever chosen on their behalf. If no hint is available the modal simply opens with nothing pre-selected.

Three providers are supported: Cloudflare’s CF-IPCountry header, the MaxMind GeoIP Detect plugin, and any plugin implementing WordPress’s geoip_country_code filter. Hints are cached for an hour per visitor.

How are receipt numbers generated? Can there be gaps?

Each account gets its own sequence, restarting annually, formatted as country-year-sequence — for example US-2026-00001 and CA-2026-00001 run independently.

Gaps are possible and are not a fault. Numbers are allocated atomically at the moment a donation record is created, so an allocated number is never reused even under simultaneous donations; but if a donation is later deleted, its number is not recycled. If your jurisdiction requires strictly gapless receipt numbering, verify that this satisfies your auditor before relying on it.

What does the plugin store on each donation?

Three pieces of metadata: which account processed it (_ador_processing_account_id), the country the donor selected (_ador_donor_country), and the receipt number allocated for it (_ador_receipt_number). No other donor data is stored by this plugin — everything else about a donation lives in GiveWP as usual.

The account that processed a donation is recorded at payment time and is not editable afterwards, because it reflects which legal entity actually received the money.

What happens when I uninstall?

Deleting the plugin through the Plugins screen removes its two database tables, its options, its per-account receipt templates and sequences, and its transients. Deactivating alone changes nothing, so you can deactivate safely while troubleshooting.

Donation records, receipt numbers already written to donation metadata, and GiveWP’s own data are untouched — but once the accounts table is gone, receipt email tags for past donations resolve to empty strings. Export anything you need first.

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. Each account needs its own credentials and its own webhook, but you no longer have to create a PayPal Developer app per account: Connect with PayPal onboards each one through GiveWP’s approved partner and stores the resulting credentials for you, and the webhook can be registered from the Accounts list. Entering a Client ID and Secret from your own Developer app is still supported if you prefer it.

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, and it is worth doing. Add sandbox accounts exactly the way you add live ones — Connect with PayPal works against the sandbox too, and manual Client ID and Secret entry still works if you prefer. Each account records the environment it belongs to, so live and sandbox accounts for the same merchant can sit side by side without interfering.

Switch GiveWP into test mode while you do this: routing only uses accounts whose environment matches GiveWP’s current mode, so sandbox accounts are inert in live mode and vice versa. Sandbox webhooks need a publicly reachable HTTPS URL, so 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?

First check that PDF Receipts is enabled under the plugin’s Settings tab — it is off by default. dompdf ships inside the released package, so there is nothing to install; if you are running from a source checkout instead, run composer install to fetch it. Then look in the PHP error log for a line beginning [ADOR] PDF receipts disabled:, which names the underlying cause.

If the button appears but downloading returns “You do not have permission”, update to the latest version — releases before this one refused the download to everyone except administrators.