Setting Up the WeGive Salesforce Integration

This guide walks you through connecting WeGive to Salesforce NPSP from start to finish: confirming your Salesforce edition, installing the package, connecting the two systems, and running your first successful sync. You can complete every step here without leaving this page. If you work with a Salesforce consultant, you can hand this guide to them as is.

Do not set this up in your live Salesforce first. Start in a Salesforce Sandbox connected to your WeGive Test account, confirm everything works, then set it up a second time in your live environment. You will complete this setup twice, because Test and Live are separate systems. Building straight into Live puts your real donor and donation data at risk before you have confirmed your configuration and field mapping. More on this in Match your environments below.

Salesforce is moving from Connected Apps to External Client Apps (ECA). If your Salesforce org was created after Spring '26, or you cannot create a new Connected App, use the External Client App path below (recommended). If you already have a working Connected App, you can keep it until WeGive completes the full move to ECA.

Before You Start

Your Salesforce edition

The integration works with one of these editions:

• Enterprise

• Unlimited

• Developer

What needs to be installed

Two packages must be present in your Salesforce org:

Who can do this

You must be a Salesforce System Administrator to install the package and connect the integration. We recommend using a dedicated integration user rather than a personal admin login. The user that connects WeGive needs these permissions:

• API Enabled

• Modify All Data

• Customize Application

• View Setup and Configuration

• View All Data

Match your environments

Your WeGive Test dashboard connects to a Salesforce Sandbox, and your WeGive Live dashboard connects to a Salesforce Production org. You cannot mix them: a Test dashboard will not connect to a Production org, and a Live dashboard will not connect to a Sandbox.

Test before you build in Live. Set up and run the integration in a Salesforce Sandbox connected to your WeGive Test account first. This is where you confirm, before any data touches your live records, that:

• Your specific Salesforce configuration and data structures sync correctly

• Your governance rules and automations behave as expected

• Your field mapping is correct

Your Test and Live environments are separate. Settings, field mappings, and configuration do not carry over between them, so you must configure each dashboard on its own. Once your Test setup is confirmed, repeat these steps on your WeGive Live dashboard connected to your Salesforce Production org.

Step 1: Install the WeGive Managed Package

Choose the link that matches your Salesforce environment, then sign in as a System Administrator before clicking.

Managed package installation links:

On the install screen:

1. Choose Install for All Users.

2. Open Package Components under Additional Details to review what is included.

3. Approve any third-party access prompts.

4. Click Install.

Installation can take a few minutes. When it finishes, you will see the WeGive4SF package under your Installed Packages.

If you see "This package can't be installed. Insufficient Privileges," your login is not a System Administrator. Switch profiles or ask your Salesforce admin to install it for you.

Step 2: Connect WeGive to Salesforce

Use Option A (External Client App) if you are on a newer Salesforce org or starting fresh. This is the recommended path. Use Option B (Connected App) only if your org already runs one.

Option A: External Client App (recommended)

Create the External Client App

1. In Salesforce, go to Setup.

2. Search for External Client App and open it.

3. Click New External Client App.

4. Enter the following:

External Client App settings:

5. Add these OAuth scopes:

   • Manage user data via APIs (api)

   • Perform requests at any time (refresh_token, offline_access)

6. Under Flow Enablement, set Authorization Code and Credentials Flow to Yes and leave all others No.

7. Under Security, set both Require Secret for Web Server Flow and Require Secret for Refresh Token Flow to Yes.

8. Click Save.

Use the same callback URL for both production and sandbox. A new External Client App can take up to 10 minutes to activate. If you get an OAUTH_APPROVAL_ERROR_GENERIC when connecting, wait a few minutes and try again.

Relax IP restrictions

1. Open the app's detail page and click Manage or Edit Policies.

2. Set IP Relaxation to Relax IP restrictions.

3. Save.

Add WeGive as a remote site

1. In Salesforce, go to Security > Remote Site Settings.

2. Click New Remote Site and enter:

Remote site settings:

3. Save.

Copy your credentials

On the External Client App detail page, copy the Consumer Key and Consumer Secret. You will paste these into WeGive in Step 3.

Option B: Connected App (existing orgs only)

Use this only if your org already supports creating Connected Apps. Salesforce stopped allowing new Connected App creation as of Spring '26.

Create the Connected App

1. In Salesforce, go to Setup, search for App Manager, and open it.

2. Click New Connected App and enter:

Connected App settings:

3. Click Save.

Enable the username-password flow (orgs created after Summer 2023)

1. In Setup, search for OAuth and OpenID Connect Settings.

2. Enable Allow OAuth Username-Password Flows.

Relax IP restrictions and add the remote site

1. In App Manager, open the WeGive app, click Manage, then Edit Policies, and set IP Relaxation to Relax IP Restrictions. Save.

2. Go to Security > Remote Site Settings, click New Remote Site, and enter wegive_api with the URL https://super.givelist.app. Save.

Copy your credentials

In App Manager, open the WeGive app, click View, scroll to API (Enable OAuth Settings), click Manage Consumer Details, and copy the Consumer Key and Consumer Secret.

Step 3: Configure Required Exclusions

This is the last step you do in Salesforce. You must add your WeGive Integration user to the Usernames to Exclude field on three NPSP trigger handlers. Do this for every NPSP org running the integration. Skipping it causes sync errors and duplicate or conflicting records.

To reach the trigger handlers, open the App Launcher in Salesforce, search for Trigger Handlers, and open the Trigger Handlers list. For each handler in the table below, open its record and add the WeGive Integration user's username to the Usernames to Exclude field.

Add the WeGive Integration user to the exclude list on these handlers:

Do not exclude the user from the PMT_Payment_TDTM handler on the Opportunity object. That is a separate handler. WeGive already sets npe01__Do_Not_Automatically_Create_Payment__c = true on the Opportunities it pushes, which handles the Opportunity-side trigger correctly.

Step 4: Connect in WeGive

Your Salesforce setup is now complete. The rest happens in the WeGive dashboard.

1. In the WeGive dashboard, go to Integrations > Salesforce NPSP > General Settings.

2. Paste in the Consumer Key and Consumer Secret you copied in Step 2.

3. If you used Option A (External Client App): click Connect with Salesforce, then log in and approve access when redirected to Salesforce.

4. If you used Option B (Connected App): enter your Salesforce username and password, then set the Instance URL to https://login.salesforce.com/ for production or https://test.salesforce.com/ for sandbox.

5. Click Test Connection.

6. When the test succeeds, click Sync Salesforce to turn the integration on.

Step 5: Configure Your Field Mapping

WeGive comes with default field mappings, so your core data (supporters, donations, campaigns, and so on) syncs without any extra setup. If you need to map additional or custom fields, do it now, before your first full sync.

Mapping before you pull matters: the initial sync brings records in using whatever mappings are in place at the time. If you pull first and add mappings later, you will need to re-sync to populate the new fields. Setting them up first means your data comes in mapped correctly the first time, which is also what you want to validate in Test before going live.

Before the first full sync, configure all of the following:

• Field mappings for supporters and companies. Map any custom or additional fields. Companies (Salesforce Accounts) are mapped separately from individual supporters (Contacts), so set up both. See Add New Fields to Salesforce Mapping Rules.

• State and country picklist mappings. Configure these for both individual supporters and companies so addresses come in correctly on the first pull. See Configuring Salesforce State and Country Picklist Mappings.

Step 6: Run Your Initial Sync

With your field mapping in place, run your first full sync to pull your existing Salesforce data into WeGive.

Recommended for everyone: turn on all pull toggles, then run Sync All. For the initial sync, go to Integrations > Salesforce NPSP > General Settings, turn on every pull object toggle, and click Sync All.

Why turn everything on for the first sync: WeGive creates records in a dependency order, and some records cannot sync until the records they rely on already exist. For example, supporters must sync before their payments. If you leave foundational objects turned off, dependent records can fail or come in incomplete. Turning all pulls on for the initial sync makes sure the underlying data is there.

Please review this before you rely on sync: read Using Sync and How Syncing Works to understand exactly what Sync All does and how record IDs behave. It is a short read and it will save you from common surprises.

For consultants and advanced users

If you know the organization does not use a particular object, you can leave that pull turned off. For example, an organization that does not use Households can turn off the Households pull. Only skip objects when you understand the data model and what depends on what, because turning off an object that other records rely on will cause missing-data errors. When in doubt, sync everything for the initial sync and refine afterward.

Step 7: Test Your First Sync

Run this test in your WeGive Test dashboard connected to your Salesforce Sandbox, before you connect anything live.

1. Create a test donation in your WeGive Test account.

2. Wait about 5 minutes.

3. In your Salesforce Sandbox, confirm a new Contact, Opportunity, and Payment appeared.

4. In WeGive, check Integrations > Salesforce NPSP > Logs for any errors.

Only move to Live after your Test sync looks correct. Then repeat Steps 1 to 6 with your WeGive Live dashboard connected to your Salesforce Production org. Remember to set up your settings and field mapping again in Live, because they do not carry over from Test.

The most common first-sync issues are field-level permission gaps, missing trigger handler exclusions, or an incorrect Instance URL. See How to Check and Update Salesforce Field-Level Permissions if you hit field errors.

You Are Connected. What Is Next

Once setup is complete, you can fine-tune what syncs and how:

• Adjust sync toggles, stage mappings, and payment method names in Integrations > Salesforce NPSP > General Settings.

• Add or adjust field mappings at any time as your needs change (see Add New Fields to Salesforce Mapping Rules). Remember to re-sync affected records so the new mappings populate.

For the complete field-by-field mapping and the technical data model (useful if a consultant wants to understand exactly how WeGive maps to Salesforce objects), see the technical reference at wegive.com/docs.