Setting Up a Donation Connection

A donation connection lets NP Ledger automatically record donations as they come in from platforms like Stripe, PayPal, Givebutter, or Donorbox. Instead of entering each donation by hand, your books update within seconds of each gift.

If your nonprofit receives online donations, manually entering each one takes time and risks mistakes. A donation connection records each donation automatically, tracks processing fees (the percentage each platform charges to process a donation, typically 2–3%), and holds the money in a transit account until the payout arrives in your bank, keeping your books accurate and up to date.

• A bank account in NP Ledger that matches where your donation platform sends payouts
• A revenue account for donation income (usually your main contributions account, e.g. "Contribution Revenue" or "Individual Contributions", created with your chart of accounts)
• An active account on the donation platform you want to connect (Stripe, PayPal, Givebutter, or Donorbox)
• Admin access to the donation platform's settings (you'll need to add a URL)

Step 1: Configure NP Ledger settings

1. Go to Organization > Donation Connections. On your Organization page, find the Organization Admin section and click the Donation Connections card.
2. Enable automatic donation sync using the toggle at the top. When enabled, donations from your connected platforms will automatically appear as transactions in NP Ledger.
3. Select a Deposit Account: this is the bank account where your donation platform sends payouts (e.g., your main checking account).
4. Select a Revenue Account: this is the category NP Ledger uses to classify donation income (usually your main contributions account, e.g. "Contribution Revenue").
5. Click Save Changes.

Tip: NP Ledger automatically creates a "Donations in Transit" account when you enable a donation connection. This tracks money between when a donor gives and when the payout (the deposit your donation platform sends to your bank, usually batching multiple donations together) arrives in your bank. You don't need to set this up yourself.

Step 2: Connect your platform

Each platform has its own section on the Donation Connections page. Find yours below and follow the instructions.

Stripe

1. Copy the NP Ledger Connection URL shown in the Stripe section of the Donation Connections page.
2. Log into your Stripe Dashboard and go to Developers > Webhooks.
3. Click "Add endpoint" and paste the NP Ledger URL.
4. Select these events: checkout.session.completed, invoice.payment_succeeded, charge.refunded, charge.dispute.funds_withdrawn.
5. Copy the Signing Secret from Stripe and paste it into the Security Key field in NP Ledger.

Taking monthly (recurring) donations? invoice.payment_succeeded is the event that records each renewal charge. The first month comes in as checkout.session.completed; every month after that arrives as an invoice. So if you leave invoice.payment_succeeded off the list, a recurring donor's first gift records but the following months quietly don't. For the fund to carry across every renewal, set the fund label on the subscription's metadata, not just the one-time checkout — see Fund Allocation Rules.

6. (Optional) Add a Restricted API Key to capture processing fees. By default, Stripe donations record the gross amount, but the per-donation Stripe processing fee shows as "—". To record the exact fee on each donation, create a Restricted Key in your Stripe Dashboard (Developers > API keys > Create restricted key) with Charges: Read and Balance transactions: Read permissions, then paste it into the Restricted API Key field in NP Ledger. This is recommended but optional. Donations record correctly either way.
7. Click Save Changes in NP Ledger.

Note: The Restricted API Key only reads charge and fee data; it cannot move money or change anything in your Stripe account. If you skip it, or if the key's permissions are wrong, donations still record at their gross amount and the fee simply shows as "—". Existing donations recorded before you add the key keep showing "—"; only donations received afterward capture the fee.

PayPal

NP Ledger creates and manages the PayPal webhook for you — you only need to paste two keys.

1. Log into the PayPal Developer Dashboard and go to Apps & Credentials.
2. Create or select your Live app.
3. Copy the Client ID and Secret and paste them into the PayPal section in NP Ledger.
4. Make sure Enable automatic donation sync is checked at the top of the page.
5. Click Connect. NP Ledger creates a webhook on your PayPal app, points it at your private Connection URL, and subscribes it to the right events automatically — there's no webhook to create or Webhook ID to copy.
6. Click Check Configuration to confirm everything is wired up.

Note: PayPal requires API credentials (Client ID + Secret) so NP Ledger can create the webhook on your behalf and verify each donation's signature. Clicking Connect again later is safe — NP Ledger reuses the existing webhook instead of creating a duplicate.

Already created a webhook by hand? Existing connections keep working. The auto-created Webhook ID (and your private Connection URL) are shown under Advanced in the PayPal section, where the Webhook ID also remains editable as a manual fallback.

Testing first? Use sandbox mode. The PayPal section has a Sandbox (testing) mode checkbox. When checked, NP Ledger talks to PayPal's sandbox (api-m.sandbox.paypal.com) instead of the live API, so you can validate the whole flow end-to-end using a PayPal sandbox app's credentials with no real money moving and no entries in your real books. To test: check Sandbox (testing) mode, paste your sandbox app's Client ID and Client Secret, click Connect (the sandbox webhook is created automatically), then click Check Configuration — it will confirm it's validating against the sandbox environment. When you're ready to go live, uncheck the box, re-enter your Live credentials, and click Connect before accepting real donations.

For developers: The NP Ledger Connection URL is per-organization and contains a secret token, so it is never published as a fixed or public URL. NP Ledger now registers this URL with PayPal automatically when the org admin clicks Connect; the URL is still visible (for reference/troubleshooting) under Advanced in the PayPal section. To validate end-to-end against PayPal sandbox, ask the admin to enable the Sandbox (testing) mode toggle described above and supply sandbox app credentials; switch back to Live before launch.

Givebutter

1. Copy the NP Ledger Connection URL from the Givebutter section.
2. Log into Givebutter and go to Settings > Developers > Webhooks.
3. Add the NP Ledger URL and select events: transaction.succeeded, refund.created.
4. Copy the Signature key from Givebutter and paste it into the Security Key field in NP Ledger.
5. Click Save Changes in NP Ledger.

Donorbox

1. Copy the NP Ledger Connection URL from the Donorbox section.
2. Log into Donorbox and go to Add-ons > API & Zapier Integration (activate it if needed), then open Webhooks.
3. Add the NP Ledger URL and select events: donation.created, donation.refunded.
4. Copy the HMAC secret from Donorbox and paste it into the Security Key field in NP Ledger.
5. Click Save Changes in NP Ledger.

Important: Donorbox webhooks require an API/Zapier addon ($17/month) or a Premium plan. Check your Donorbox plan before starting.

GiveWP (WordPress)

GiveWP doesn't get its own connection. It runs each donation through your own Stripe or PayPal account, so the gift already arrives on the Stripe or PayPal connection you set up above — there's nothing extra to wire.

The one thing worth checking is fund designation. GiveWP can pass a form or campaign name along with each gift, and NP Ledger can send the gift to the right fund from it — but only once you tell it which label to look for:

• Gifts through Stripe: GiveWP sends its form or campaign as Checkout Session metadata. Add a Fund Allocation Rule that matches on that metadata key and value.
• Gifts through PayPal: GiveWP puts its reference in PayPal's custom_id field. Add a rule that matches on custom_id.

If you don't set a rule, GiveWP gifts still record fine — they just land in your default fund, like any other gift that arrives without a designation.

Step 3: Test the connection

1. Back in NP Ledger, click the Check Configuration button next to your connected platform.
2. A green "Connected" badge appears if everything is set up correctly.
3. Make a small test donation through your platform to verify that it appears in NP Ledger within a few seconds.

Step 4: Set payout reminders (optional)

1. Scroll to the Payout Reminders section on the Donation Connections page.
2. Choose your preferred alert timing: Relaxed, Standard, or Tight. This controls how quickly NP Ledger reminds you about pending payouts that haven't been matched to a bank deposit yet.

• A green "Connected" badge appears next to the platform name after clicking Check Configuration
• Your test donation appears in the Recent Activity section at the bottom of the page
• The transaction appears in Recent Transactions on the dashboard
• A Supporter record is created (or updated) with the donor's name, email, and (for Stripe, Givebutter, and Donorbox) phone and mailing address. See How Automatic Donation Recording Works for what's populated per platform.

• Forgetting to select a deposit account or revenue account: Without these, donations will be received but can't be recorded. They'll show as "Failed" in Recent Activity.
• Copying the wrong security key: Each platform has a specific signing secret or key. Make sure you copy the webhook-specific secret, not your general API key.
• Selecting the wrong events in your platform: Only enable the specific events listed above. Enabling extra events won't cause errors, but they'll be ignored.
• Not clicking Check Configuration: Always test after setup. A missing or incorrect security key will silently fail on real donations.

Accountant note: Donation connections use a clearing account model. Incoming donations debit "Donations in Transit" (an asset) and credit revenue. When the payout settles to your bank, a settlement entry moves the net amount to your bank account and records the processing fee as an expense. This matches the ASC 606 timing of revenue recognition while tracking the payment processor's settlement cycle.