> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wegive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setting Up the WeGive Salesforce Integration

> WeGive Help Center article: 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:

| Package | Why it is needed |
| - | - |
| Nonprofit Success Pack (NPSP) | The integration reads and writes standard NPSP records. |
| WeGive Managed Package | Adds WeGive objects like Pledges, Payouts, Events, and Communication Lists. You install this in Step 1 below. |

### 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:

| Environment | Installation link |
| - | - |
| Production / Developer Edition | [https://login.salesforce.com/packaging/installPackage.apexp?p0=04tak000000UoKLAA0](https://login.salesforce.com/packaging/installPackage.apexp?p0=04tak000000UoKLAA0) |
| Sandbox / Scratch | [https://test.salesforce.com/packaging/installPackage.apexp?p0=04tak000000UoKLAA0](https://test.salesforce.com/packaging/installPackage.apexp?p0=04tak000000UoKLAA0) |

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:

   1. Name: WeGive
   2. Contact Email: [support@wegive.com](mailto:support@wegive.com)
   3. Distribution State: Local

5. Open the API (Enable OAuth Setting) :

   * Enable OAuth
   * Callback URL : [https://api.wegive.com/api/oauth/salesforce/callback](https://api.wegive.com/api/oauth/salesforce/callback)
   * OAuth Scope

     * 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 **Create**.

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:

| Field | Value |
| - | - |
| Remote Site Name | `wegive_api` |
| Remote Site URL | `https://api.wegive.com` |

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:

| Field | Value |
| - | - |
| Connected App Name | `WeGive` |
| API Name | `WeGive` |
| Contact Email | `support@wegive.com` |
| Enable OAuth Settings | Checked |
| Callback URL (production and sandbox) | `https://api.wegive.com/api/oauth/salesforce/callback` |
| Selected OAuth Scopes | Move all available scopes to Selected |
| Require Secret for Web Server Flow | Checked |
| Require Secret for Refresh Token Flow | Checked |

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://api.wegive.com`. 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:

| # | Trigger Handler Class | Object | Why exclude it |
| - | - | - | - |
| 1 | `ALLO_Allocations_TDTM` | `Allocation__c` | Prevents NPSP from auto-managing GAU Allocations on records pushed by WeGive. WeGive handles allocation data directly. |
| 2 | `PMT_Payment_TDTM` | `npe01__OppPayment__c` | Prevents NPSP from running payment validation on Payment records inserted by WeGive. WeGive sends fully formed Payment records, so NPSP validation is redundant and can hit governor limits under load. |
| 3 | `ALLO_PaymentSync_TDTM` | `Allocation__c` | Prevents NPSP from syncing allocations when WeGive creates or updates Payment records. WeGive manages allocation sync independently. |

**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](https://wegive-knowledge-base.help.usepylon.com/articles/9942025259-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](https://wegive-help-center.help.usepylon.com/articles/3843908042-configuring-salesforce-state-and-country-picklist-mappings-in-wegive).

## 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](https://wegive-help-center.help.usepylon.com/articles/6819841810-how-the-salesforce-sync-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](https://wegive-knowledge-base.help.usepylon.com/articles/3193667702-how-to-check-and-update-salesforce-field-level-permissions-for-the-system-administrator-profile) 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](https://wegive-knowledge-base.help.usepylon.com/articles/9942025259-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](https://wegive.com/docs/salesforce-npsp/data-mapping/overview).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.