Setting Up the WeGive Salesforce Integration

This guide walks through everything you need to connect WeGive to Salesforce NPSP, from confirming your Salesforce edition to completing the first successful sync.

Note: Salesforce is transitioning from Connected Apps to External Client Apps (ECA). If your Salesforce org was created after Spring '26 or you are unable to create a new Connected App, follow the ECA instructions in this guide. If you already have a Connected App working, no changes are needed until we complete the full migration to ECA.

Before You Start

Required Salesforce Edition

The integration requires one of the following:

• Enterprise Edition

• Unlimited Edition

• Developer Edition

Required Packages in Salesforce

Nonprofit Success Pack (NPSP) must be installed. The integration uses several NPSP objects including npe01__OppPayment__c, npe03__Recurring_Donation__c, and npsp__Allocation__c.

WeGive Managed Package must also be installed to support custom objects like Pledges, Payouts, Events, and Communication Lists.

• Production / Developer Edition Orgs: https://login.salesforce.com/packaging/installPackage.apexp?p0=04tak000000PYcnAAG

• Sandbox / Scratch Orgs: https://test.salesforce.com/packaging/installPackage.apexp?p0=04tak000000PYcnAAG

You must be logged in as a System Administrator to install the package. If you see an "Insufficient Privileges" error, either switch to a System Administrator profile or ask your Salesforce admin to complete the installation.

When prompted, select Install for All Users, then confirm and approve any third-party access prompts.

Required Salesforce User Permissions

The Salesforce user account used for the integration must have:

• API Enabled

• Modify All Data

• Customize Application

• View Setup and Configuration

• View All Data

Field-Level Security

All fields involved in the integration must be visible and editable by the integration user, including custom fields and managed package fields. Even System Administrators may lack access to certain custom or managed package fields by default. See [How to Check and Update Salesforce Field-Level Permissions] if you encounter field-related sync errors.

Environment Matching

Both systems must be the same type. A WeGive sandbox connects to a Salesforce sandbox, and a WeGive production account connects to a Salesforce production org. You cannot mix environments.

Option A: Connected App Setup (Legacy)

Use this method if your Salesforce org still supports creating Connected Apps. Salesforce deprecated new Connected App creation as of Spring '26, so if you cannot create one, skip to Option B: External Client App (ECA) Setup.

Step A1: Create a Connected App in Salesforce

1. Log into Salesforce and go to Setup.

2. Search for App Manager in the navigation search bar and select it.

3. Click New Connected App.

4. Fill in the following fields:

Connected App field values:

5. Click Save.

Important: Use https://super.givelist.app as the Callback URL for both Salesforce production and sandbox environments.

Step A2: Enable Username-Password Flow (Post-Summer 2023 Orgs Only)

If your Salesforce instance was created after Summer 2023, you must explicitly enable the OAuth username-password flow. The integration will not connect without this step.

1. Go to Setup and search for OAuth and OpenID Connect Settings.

2. Find the WeGive connected app.

3. Enable Allow OAuth Username-Password Flows.

Step A3: Get Your Consumer Key and Secret

1. In the App Manager, find the WeGive app and click View.

2. Scroll to the API (Enable OAuth Settings) section.

3. Click Manage Consumer Details.

4. Copy the Consumer Key (Client ID) and Consumer Secret (Client Secret). You'll paste these into WeGive in Step A6.

Step A4: Relax IP Restrictions

1. Return to the App Manager and click Manage on the WeGive app.

2. Click Edit Policies.

3. Under IP Relaxation, select Relax IP Restrictions.

4. Save.

Step A5: Add WeGive as a Remote Site

1. From the Salesforce home screen, go to Security > Remote Site Settings.

2. Click New Remote Site and fill in:

Remote site values for the legacy Connected App:

3. Save.

Step A6: Enter Credentials in WeGive

1. In the WeGive dashboard, navigate to Integrations > Salesforce.

2. Open General Settings.

3. Paste in the Consumer Key (Client ID) and Consumer Secret (Client Secret) from Step A3.

4. Enter your Salesforce Username and Password.

5. Set the Instance URL:

   • Sandbox: https://test.salesforce.com/

   • Production: https://login.salesforce.com/

6. Click Test Connection.

7. If the test succeeds, click Sync Salesforce to enable the integration.

Option B: External Client App (ECA) Setup

Use this method if your Salesforce org does not allow creating Connected Apps (Spring '26 and later) or if you prefer to use the newer ECA standard. This is the recommended path going forward.

Step B1: Create an External Client App in Salesforce

1. Log into Salesforce and go to Setup.

2. Search for External Client App and select it.

3. Click New External Client App.

4. Fill in the following fields:

External Client App field values:

5. Under Flow Enablement:

   • Enable Authorization Code and Credentials Flow: Yes

   • All others: No

6. Under Security:

   • Require Secret for Web Server Flow: Yes

   • Require Secret for Refresh Token Flow: Yes

7. Click Save.

Important: Use https://api.wegive.com/api/oauth/salesforce/callback as the Callback URL for both Salesforce production and sandbox environments. The ECA may take up to 10 minutes to become active. If you get an OAUTH_APPROVAL_ERROR_GENERIC, wait and retry.

Step B2: Configure ECA Policies

1. Go to the ECA detail page and click Manage or Edit Policies.

2. Set IP Relaxation to Relax IP restrictions.

3. Save.

Step B3: Get Your Consumer Key and Secret

1. On the ECA detail page, locate the Consumer Key and Consumer Secret.

2. Copy both values. You'll paste these into WeGive in Step B5.

Step B4: Add WeGive as a Remote Site

1. From the Salesforce home screen, go to Security > Remote Site Settings.

2. Click New Remote Site and fill in:

Remote site values for the ECA setup:

3. Save.

Step B5: Connect in WeGive

1. In the WeGive dashboard, navigate to Integrations > Salesforce.

2. Open General Settings.

3. Paste in the Consumer Key (Client ID) and Consumer Secret (Client Secret) from Step B3.

4. Click Connect with Salesforce to initiate the OAuth authorization flow.

5. You will be redirected to Salesforce to authorize the connection. Log in and approve access.

6. Once redirected back to WeGive, click Test Connection to verify.

7. If the test succeeds, click Sync Salesforce to enable the integration.

After Setup (Both Methods)

Step 7: Configure Required NPSP Trigger Handler Exclusions

Before going live, you must configure three NPSP trigger handlers to exclude the WeGive integration user. Skipping this step will cause sync errors and data conflicts.

See Required Exclusions for the full instructions.

Sync Settings and Flags

Once the integration is connected, the following settings are available in General Settings:

Available sync settings:

Stage Mappings

WeGive maps transaction statuses to Salesforce Opportunity Stage Names. The defaults are:

Default WeGive status to Salesforce stage mappings:

These can be customized in integration settings to match your org's existing stage names.

Payment Method Names

You can define custom display names for payment methods that appear on Opportunity and Payment records in Salesforce:

• Credit Card

• Bank / ACH

• PayPal

Testing Your Integration

After setup:

1. Create a test donation in your WeGive sandbox.

2. Wait approximately 5 minutes.

3. Check Salesforce for the new Contact, Opportunity, and Payment.

4. Review Integrations > Salesforce > Logs in WeGive for any errors.

If errors appear, the most common causes are field-level permission issues, missing trigger handler exclusions, or an incorrect Instance URL. See [Monitoring and Troubleshooting Your Salesforce Integration] for help reading the logs.