​

Opportunity (Transactions/Donations) - Field Mapping

Salesforce Object: Opportunity
WeGive Model: Transaction

​

How Opportunity Data Syncs

This table shows all fields that sync between WeGive and Salesforce for transactions/donations. Direction:

• Import from Salesforce - Data imports from Salesforce into WeGive only
• Export to Salesforce - Data exports from WeGive to Salesforce only
• Both Ways - Data syncs in both directions

Mapping Types:

• Configurable - Can be customized via integration settings or mapping rules
• Configurable (mapping rule) - Reaches Salesforce only when a mapping rule for it exists
• Hard-coded - Built into the integration logic and cannot be changed

---

​

Sync Configuration

Opportunity pulls and pushes are controlled by the Pull transactions and Push transactions toggles in the integration’s Sync Configuration. The settings below shape the behavior once a pull or push runs:

---

​

Sync Triggers

​

From WeGive to Salesforce (Export)

Opportunity data is exported from WeGive to Salesforce when:

• Transaction Created: A new donation/transaction is created in WeGive
• Transaction Updated: An existing transaction is modified in WeGive (e.g., status changed, amount updated, campaign assigned)

The export happens automatically after the create or update action in WeGive when Push transactions is enabled.

​

From Salesforce to WeGive (Import)

Opportunity data is imported from Salesforce to WeGive based on:

• Last Modified Date: WeGive periodically polls Salesforce for Opportunities that have been modified since the last sync
• Sync Frequency: The integration checks for updated Opportunities on a scheduled basis (frequency varies by integration configuration)
• Modified Field Tracking: Only Opportunities with a LastModifiedDate newer than the last successful sync are pulled into WeGive

When uses_payments is enabled, the pull queries the Payment object (npe01__OppPayment__c) instead of Opportunities, and only Payments with npe01__Paid__c = TRUE are returned. A change to either the Payment or its parent Opportunity LastModifiedDate triggers the import. This means:

• Creating a new Opportunity in Salesforce will import it to WeGive on the next sync cycle (with uses_payments, only once it has a paid Payment)
• Updating an existing Opportunity in Salesforce will trigger an import to WeGive on the next sync cycle
• The sync is based on Salesforce’s LastModifiedDate field, not individual field changes

​

Deleted Opportunities

When pull_deleted_transactions is enabled, the integration queries Opportunities with IsDeleted = true in the sync window and soft-deletes the matching WeGive transaction (matched by stored Salesforce ID).

---

​

Sync Process Overview

​

Opportunity-Level Synchronization

WeGive syncs donations and transactions at the Opportunity level in Salesforce, which is NPSP’s standard object for tracking donations. Each transaction in WeGive corresponds to an Opportunity in Salesforce, maintaining the complete donation record including donor information, amount, campaign attribution, and tribute details.

​

Pulling Data from Salesforce

When pulling data from Salesforce, WeGive queries Opportunities (or Payments) based on the last modified date. The base query always reads Id, CreatedDate, Amount, StageName, RecordTypeId, ContactId, AccountId, CampaignId, npe03__Recurring_Donation__c and npe01__Is_Opp_From_Individual__c; any additional fields come from your Opportunity (donation) mapping rules. When uses_payments is enabled, Payment-level mapping rules are also applied, with Opportunity-level values taking precedence when both map to the same WeGive field. The import then:

• Matches the WeGive transaction by stored salesforce_id (or by salesforce_payment_id when uses_payments is enabled) and creates a new transaction if none is found
• Resolves the owner from the mapped Contact (owner.salesforce_id) or Account (owner.salesforce_account_id) according to npe01__Is_Opp_From_Individual__c, and fails the record if no owner exists in WeGive
• Resolves campaign, fund, pledge, campaign fundraiser and recurring donation links from mapped Salesforce IDs
• Maps StageName to a WeGive status (see Picklist Values)
• Derives is_tax_deductible and hidden from the Opportunity’s Record Type unless a mapping rule supplies them directly
• Stores the imported amount in cents and sets the transaction date to the mapped date at 17:00:00

​

Pushing Data to Salesforce

When a Transaction record is created or updated in WeGive, the integration first ensures the related records exist in Salesforce: the donor (Contact or Account), campaign, fund and recurring donation are pushed if they have no Salesforce ID yet, and the payment method is pushed as an accessory (a payment method failure never blocks the gift). It then compiles the Opportunity payload, which includes:

• Automatic Name Generation: On create, the name is {donor name} {MM-YY} (for example “John Smith 01-24”) unless a mapping rule supplies one
• Stage Name Mapping: Transaction status is mapped to the configured stage_* values
• Amount Calculation: Net donation amount (amount minus fees) is calculated and converted to dollars
• Type Assignment: “Recurring” or “One-Time” based on whether the transaction is linked to a recurring donation
• Record Type Assignment: Based on whether the donation is tax-deductible
• Tribute Handling: Populates tribute/memorial information when present

NPSP Payment Creation Prevention: The integration sets npe01__Do_Not_Automatically_Create_Payment__c to true on create to prevent NPSP from automatically creating Payment records. The WeGive integration handles Payment creation itself when uses_payments is enabled.

​

Opportunity Field Mappings

​

Picklist Values

​

StageName (Opportunity Stage)

Export. The StageName written is the configured stage setting for the transaction’s status: The stage values themselves are configured in your integration settings to match your Salesforce org’s Stage picklist. The StageName is recalculated on every create and update. Import. An Opportunity’s StageName is mapped to a WeGive status in this order of precedence:

1. stage_status_map, if it contains the StageName
2. The configured stage_success, stage_pending, stage_refunded, stage_failed values (checked in that order, so push and pull agree)
3. A built-in fallback list:

---

​

Important Notes

​

Amount Calculation

When exporting to Salesforce, the Opportunity Amount is calculated as (amount - fee) / 100 to show the net donation amount in dollars. WeGive stores amounts in cents internally, so the division by 100 converts to the dollar amount expected by Salesforce. Example: If a donor gives $100 with a $3 processing fee:

• WeGive stores: amount = 10000 (cents), fee = 300 (cents)
• Salesforce receives: Amount = $97.00 (net donation)

On import, the Salesforce dollar amount is multiplied by 100 and rounded to the nearest cent.

​

Automatic Name Generation

If no mapping rule supplies a name when creating an Opportunity, WeGive generates one using the format {donor name} {MM-YY}:

• “John Smith 01-24”
• “ABC Corporation 12-23”

​

Recurring vs One-Time Donations

The Type field is automatically determined based on the transaction’s relationship to a recurring donation:

• Type = “Recurring” - Transaction has a scheduled_donation_id
• Type = “One-Time” - Transaction has no scheduled_donation_id

​

Tribute/Honoree Logic

Tribute fields are populated on create only:

• If tribute information exists, npsp__Tribute_Type__c is set to “Honor”
• npsp__Honoree_Name__c contains the honoree name (null when there is no tribute)

​

Record Type Assignment

On export, the RecordTypeId is assigned from the transaction’s is_tax_deductible flag:

• Tax-deductible: tax_deductible_record_type_id, or if unset, the Record Type named “Donation”
• Non-tax-deductible: service_revenue_record_type_id, or if unset, the Record Type named “Service Revenue”
• If neither resolves, no Record Type is sent

On import, an Opportunity whose Record Type developer name is in service_revenue_record_types is marked not tax-deductible, and one in hidden_record_types is marked hidden, unless a mapping rule supplies those fields directly.

​

Create-Only Fields

The following defaults are only set when creating a new Opportunity:

• Name, LeadSource, AccountId, ContactId
• npsp__Tribute_Type__c, npsp__Honoree_Name__c
• npe01__Do_Not_Automatically_Create_Payment__c

Mapping-rule fields are create-only when the rule’s create_only flag is set.

​

Update Behavior

When updating an existing Opportunity, the default payload contains:

• CloseDate, CampaignId, StageName, npe03__Recurring_Donation__c, Type, Amount
• RecordTypeId when one resolves

plus any mapping-rule fields not flagged create-only.

---

​

Opportunity Matching & Create/Update Logic

​

Step 1: Check for Existing Salesforce Opportunity ID

• If salesforce_id exists: UPDATE the existing Opportunity
• If not: acquire a per-transaction lock (to prevent duplicate creation by concurrent jobs), then continue

​

Step 2: Recurring Installment Matching

If the transaction belongs to a recurring donation that already has a Salesforce ID, the integration looks for an existing Opportunity on that Recurring Donation with StageName = 'Pledged'. If one exists, it is adopted and updated instead of creating a new Opportunity. With uses_payments, an existing Payment on that Opportunity is adopted as well.

​

Step 3: Create

Otherwise a new Opportunity is inserted and its ID stored on the transaction.

​

Why This Matters

Unlike Contacts and Accounts, Opportunities are not matched by email, name, or other identifying information. Apart from the Pledged installment match above, each transaction creates a unique Opportunity unless it already has a Salesforce ID stored.

​

Legacy Single Allocation

When enable_fund_allocations is off, the transaction has a fund, and fund_api_name is not set, the integration creates or updates a single npsp__Allocation__c linking the Opportunity to the fund’s GAU (adopting an NPSP-created default allocation if one already exists). See the GAU & Allocation page.

​

Payment (npe01__OppPayment__c) - Field Mapping

Salesforce Object: npe01__OppPayment__c
WeGive Model: Transaction (when uses_payments = true)

​

How Payment Data Syncs

Payments are only created when the integration setting uses_payments is enabled.

---

​

Sync Triggers

​

From WeGive to Salesforce (Export)

Payment data is exported alongside the Opportunity when a transaction is created or updated in WeGive and uses_payments is enabled.

​

From Salesforce to WeGive (Import)

When uses_payments is enabled, the transaction pull queries npe01__OppPayment__c records where npe01__Paid__c = TRUE and either the Payment or its Opportunity was modified since the last sync. Unpaid Payments are never imported. Each imported Payment becomes (or updates) one WeGive transaction, matched by salesforce_payment_id, so an Opportunity with several paid Payments produces several WeGive transactions.

---

​

Sync Process Overview

​

Pulling Data from Salesforce

The Payment pull reads Id, CreatedDate and npe01__Payment_Amount__c from the Payment, plus the parent Opportunity’s StageName, RecordTypeId, ContactId, AccountId, CampaignId, npe03__Recurring_Donation__c and npe01__Is_Opp_From_Individual__c. Opportunity-level mapping rules are applied to the parent Opportunity and Payment-level mapping rules to the Payment; when both map to the same WeGive field, the Opportunity value wins. Other Payment fields (date, method, paid flag) are imported only if a Payment-level mapping rule maps them.

​

Pushing Data to Salesforce

The Payment payload includes:

• Payment Amount: Net amount after fees, in dollars
• Payment Date: Transaction date, Y-m-d in the organization timezone
• Payment Method: From the payment method name settings (see Picklist Values)
• Paid flag: Based on transaction status (see Payment Status Logic)
• Processing Details: Fee, fee covered amount, payout and card details are available to Payment mapping rules

The Payment is linked to its parent Opportunity via npe01__Opportunity__c on create.

​

Payment Field Mappings

Other values exposed to Payment mapping rules: payout, payout_date, original_payout, original_payout_date, fund, calculated_fees_paid, calculated_fees_paid_dollars, and the transaction’s custom fields. Whether a rule field is create-only depends on the rule’s create_only flag.

​

Picklist Values

​

npe01__Payment_Method__c (Payment Method)

The Payment Method value is taken from three integration settings keyed by the transaction’s payment source: If the resolved name is blank, the integration falls back on the transaction’s payment_type: check writes “Check” and cash writes “Cash”. Any other combination leaves the field empty. There are no other built-in values; set the three name settings to values that exist in your org’s Payment Method picklist.

---

​

Important Notes

​

When Payments Are Created

Payment records are only created when uses_payments = true. When disabled, all transaction data goes into the Opportunity record only. When to Enable uses_payments:

• You want detailed payment tracking separate from donation commitments
• You want to use NPSP’s payment rollup features
• You need payment-level reporting

When to Disable uses_payments:

• You prefer one record per donation
• Your organization does not use NPSP’s payment features
• You rely on the allocation subquery during transaction pulls

​

Payment Status Logic

The npe01__Paid__c flag is set from the transaction status and always overrides any mapping rule value: Marking a still-pending Payment as paid would trigger NPSP automation that closes the Opportunity and syncs back as successful, which can prevent a scheduled charge from running. The integration therefore only sends true when money has actually moved.

​

Legacy Integration Note

When is_legacy is enabled, the following fields are removed from the Payment payload:

• npsp__Donor_Cover_Amount__c
• npsp__Batch_Number__c
• npsp__Gateway_Payment_ID__c
• npsp__Total_Transaction_Fees__c

​

Create-Only Fields

npe01__Opportunity__c is only set on create. Mapping-rule fields are create-only when the rule’s create_only flag is set.

​

Update Behavior

When updating an existing Payment, the default payload contains npe01__Paid__c, npe01__Payment_Amount__c, npe01__Payment_Date__c and npe01__Payment_Method__c, plus any mapping-rule fields not flagged create-only.

---

​

Payment Matching & Create/Update Logic

​

Step 1: Check for Existing Salesforce Payment ID

• If salesforce_payment_id exists: UPDATE the existing Payment
• If not: INSERT a new Payment linked to the Opportunity and store its ID

When a recurring installment adopts an existing Pledged Opportunity (see above), the first Payment already on that Opportunity is adopted too.

​

Why This Matters

Payments are matched only by stored Salesforce Payment ID. If a transaction loses its salesforce_payment_id reference in WeGive, a duplicate Payment is created on the next push.

​

Related Documentation

• Data Mapping Overview - object index and cross-cutting data conventions
• Recurring Donation - how installment Opportunities link to Recurring Donations
• GAU & Allocation - fund allocations on Opportunities
• Soft Credits - soft credits on Opportunities

Verified against the integration source, September 2026.