​

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
• Hard-coded - Built into the integration logic and cannot be changed

---

​

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.

​

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

This means:

• Creating a new Opportunity in Salesforce will import it to WeGive on the next sync cycle
• 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

---

​

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 based on the last modified date and any specific filtering criteria. The integration pulls comprehensive data from the Opportunity record, including all standard and custom fields that have been mapped. This data is used to create or update the corresponding WeGive Transaction record, maintaining all the necessary relationships to donors, campaigns, and recurring donations. The import process includes special handling for recurring donation relationships, ensuring that one-time and recurring gifts are properly categorized and linked.

​

Pushing Data to Salesforce

When a Transaction record is created or updated in WeGive, the integration compiles a payload for the Salesforce Opportunity object. This payload includes all mapped fields and ensures that the Opportunity record is properly created or updated in Salesforce. The integration handles complex logic including:

• Automatic Name Generation: If no transaction name is provided, WeGive generates one using the format “[donor name] [month-year]”
• Stage Name Mapping: Transaction status is mapped to appropriate Opportunity Stage values
• Amount Calculation: Net donation amount (amount minus fees) is calculated and converted to dollars
• Type Assignment: Automatically sets “Recurring” or “One-Time” based on whether the transaction is linked to a recurring donation
• Record Type Assignment: Assigns the appropriate Record Type 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 to prevent NPSP from automatically creating Payment records. This is because the WeGive integration handles payment creation separately (when uses_payments is enabled), ensuring better control over payment record creation and avoiding duplicates.

​

Opportunity Field Mappings

​

Picklist Values

​

StageName (Opportunity Stage)

The integration automatically maps transaction status to Salesforce Opportunity Stage: Configuration: These stage mappings can be customized in your integration settings to match your Salesforce org’s Stage Name picklist values. This allows you to align with your organization’s specific opportunity stages. Update Behavior: On both create and update operations, the StageName is dynamically set based on the transaction’s current status in WeGive.

---

​

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)

​

Automatic Name Generation

If no transaction name is provided when creating an Opportunity, WeGive automatically generates a name using the format: {donor.name} {month-year} Examples:

• “John Smith 01-2024”
• “ABC Corporation 12-2023”

This ensures all Opportunities have meaningful, identifiable names in Salesforce.

​

Payment Creation Prevention

The field npe01__Do_Not_Automatically_Create_Payment__c is always set to true to prevent NPSP from automatically creating Payment records. This is critical because:

• The WeGive integration handles Payment creation separately when uses_payments = true
• Prevents duplicate Payment records from being created
• Gives the integration full control over the payment lifecycle

​

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 (part of a recurring donation plan)
• Type = “One-Time” - Transaction has no scheduled_donation_id (standalone donation)

This cannot be manually overridden and is always calculated based on the transaction’s relationship.

​

Tribute/Honoree Logic

Tribute fields are only populated when the transaction includes tribute/memorial information:

• If tribute information exists, npsp__Tribute_Type__c is set to “Honor”
• The npsp__Honoree_Name__c field contains the name of the person being honored or memorialized
• If no tribute information exists, these fields remain empty

​

Record Type Assignment

The RecordTypeId is dynamically assigned based on the transaction’s is_tax_deductible flag:

• Tax-deductible donations receive one Record Type
• Non-tax-deductible donations receive a different Record Type
• This is queried dynamically from your Salesforce org’s Record Type configuration

​

Lead Source

The LeadSource field is always set to “Web” for all donations coming from WeGive, indicating that the donation originated from an online source.

​

Create-Only Fields

Several fields are only set during the creation of a new Opportunity and cannot be updated afterwards:

• AccountId - Donor’s Account relationship
• ContactId - Donor’s Contact relationship
• npe03__Recurring_Donation__c - Recurring donation relationship
• npe01__Do_Not_Automatically_Create_Payment__c - Payment prevention flag

These fields establish the core relationships for the Opportunity and are locked after creation to maintain data integrity.

​

Update Behavior

When updating an existing Opportunity, only the following fields are modified:

• CloseDate - Transaction date
• CampaignId - Campaign assignment
• StageName - Opportunity stage (based on status)
• npe03__Recurring_Donation__c - Recurring donation link
• Type - Recurring or One-Time
• Amount - Donation amount (net of fees)

All other fields remain unchanged during updates to preserve the original donation context.

---

​

Opportunity Matching & Create/Update Logic

When WeGive exports a transaction to Salesforce, the integration uses the following logic:

​

Step 1: Check for Existing Salesforce Opportunity ID

The integration first checks if the WeGive transaction already has a salesforce_id stored:

• If Salesforce Opportunity ID exists: The integration will UPDATE the existing Opportunity record in Salesforce
• If no Salesforce Opportunity ID exists: The integration creates a NEW Opportunity in Salesforce

​

Why This Matters

Unlike Contacts and Accounts, Opportunities are not matched by email, name, or other identifying information. Each transaction creates a unique Opportunity record unless it already has a Salesforce ID stored. This approach ensures:

• Every donation is tracked as a separate, distinct Opportunity
• No risk of accidentally merging different donations
• Updates only modify the correct, linked Opportunity
• Complete donation history is preserved in both systems

Important: Because Opportunities are never matched by attributes (only by stored Salesforce ID), if a transaction loses its salesforce_id reference in WeGive, it will create a duplicate Opportunity in Salesforce on the next sync. Always maintain the Salesforce ID relationship for transactions to prevent duplication.

​

Payment (npe01__OppPayment__c) - Field Mapping

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

​

How Payment Data Syncs

This table shows all fields that sync between WeGive and Salesforce for payment records. Payments are only created when the integration setting uses_payments is enabled. 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
• Hard-coded - Built into the integration logic and cannot be changed

---

​

Sync Triggers

​

From WeGive to Salesforce (Export)

Payment data is exported from WeGive to Salesforce when:

• Payment Created: A new transaction is processed in WeGive (and uses_payments = true)
• Payment Updated: An existing transaction is modified in WeGive (e.g., status changed, amount updated)

The export happens automatically after the create or update action in WeGive, but ONLY if the uses_payments setting is enabled for your integration.

​

From Salesforce to WeGive (Import)

Payment data is imported from Salesforce to WeGive based on:

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

This means:

• Creating a new Payment in Salesforce will import it to WeGive on the next sync cycle
• Updating an existing Payment 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

---

​

Sync Process Overview

​

Payment-Level Synchronization

WeGive syncs transaction payment details at the Payment level in Salesforce when uses_payments = true. This follows NPSP’s model where Opportunities represent donation commitments and Payments represent the actual payment transactions. Each transaction in WeGive can create both an Opportunity and a Payment record in Salesforce.

​

When Payments Are Created

Payment records are only created when the integration setting uses_payments = true. When this setting is disabled, all transaction data goes into the Opportunity record only, and no separate Payment records are created.

​

Pulling Data from Salesforce

When pulling data from Salesforce, WeGive queries Payment records based on the last modified date. The integration pulls comprehensive payment data including payment amounts, dates, methods, and processing details. This data is used to update the corresponding WeGive Transaction record.

​

Pushing Data to Salesforce

When a Transaction record is created or updated in WeGive (and uses_payments = true), the integration compiles a payload for the Salesforce Payment object. This payload includes:

• Payment Amount: Net amount after fees, converted to dollars
• Payment Date: Transaction creation date
• Payment Method: Mapped from WeGive payment types
• Payment Status: Based on transaction status (paid/unpaid)
• Processing Details: Gateway ID, batch number, fees, and card details

The Payment is automatically linked to its parent Opportunity via the npe01__Opportunity__c field.

​

Payment Field Mappings

​

Picklist Values

​

npe01__Payment_Method__c (Payment Method)

The integration maps WeGive payment types to Salesforce Payment Method values:

​

Configuration: Payment method mappings can be customized in your integration settings to match your Salesforce org’s Payment Method picklist values. This allows you to align with your organization’s specific payment categorization.

Dynamic Mapping: The integration first checks source_type, then falls back to payment_type if source_type is not available, ensuring the most accurate payment method is recorded.

---

​

Important Notes

​

When Payments Are Created

Payment records are only created when the integration setting uses_payments = true. This setting determines whether the integration creates separate Payment records or includes all payment information in the Opportunity record only. When to Enable uses_payments:

• You want detailed payment tracking separate from donation commitments
• You need to track multiple payments per opportunity (installments)
• You want to use NPSP’s payment rollup features
• You need payment-level reporting

When to Disable uses_payments:

• You prefer simpler one-record-per-donation tracking
• You don’t need the additional complexity of separate payment records
• Your organization doesn’t use NPSP’s payment features

​

Payment vs Opportunity

Understanding the distinction between these two objects:

• Opportunity = The donation commitment/pledge/intention
• Payment = The actual payment transaction details

This follows NPSP’s model where one Opportunity can have multiple Payments (such as installments on a pledge).

​

Payment Amount Calculation

The payment amount is calculated as (amount - fee) / 100 to show the net payment amount in dollars:

• WeGive stores amounts in cents
• The division by 100 converts to dollars for Salesforce
• Fees are subtracted to show the net amount received

Example: If a donor gives $100 with a $3 processing fee:

• WeGive stores: amount = 10000 (cents), fee = 300 (cents)
• Salesforce Payment receives: npe01__Payment_Amount__c = $97.00 (net payment)

​

Payment Status Logic

The npe01__Paid__c field is set based on the transaction status: This indicates whether the payment has actually been collected or not.

​

Legacy Integration Note

For legacy integrations (older integration setups), the following fields are excluded from export to maintain compatibility:

• npsp__Donor_Cover_Amount__c
• npsp__Batch_Number__c
• npsp__Gateway_Payment_ID__c
• npsp__Total_Transaction_Fees__c

If your integration was set up before these fields were added, they will not be synced to avoid potential field permission or mapping issues.

​

Card Details

Card-specific fields are only populated when the payment method is a credit or debit card:

• npsp__Card_Last_4__c - Last 4 digits of the card number
• npsp__Card_Network__c - Card issuer (Visa, Mastercard, American Express, Discover, etc.)

For non-card payment methods (ACH, PayPal, etc.), these fields remain empty.

​

Create-Only Fields

Several fields are only set during the creation of a new Payment and cannot be updated afterwards:

• npe01__Opportunity__c - Link to parent Opportunity
• npsp__Gateway_Payment_ID__c - WeGive transaction ID
• npsp__Donor_Cover_Amount__c - Fee coverage amount
• npsp__Card_Last_4__c - Card last 4 digits
• npsp__Card_Network__c - Card network/issuer

These fields establish the core payment details and are locked after creation to maintain audit integrity.

​

Update Behavior

When updating an existing Payment, only the following fields are modified:

• npe01__Paid__c - Payment status
• npe01__Payment_Amount__c - Payment amount
• npe01__Payment_Date__c - Payment date
• npe01__Payment_Method__c - Payment method

This ensures that the original payment context is preserved while allowing for corrections to the payment details.

​

Gateway Payment ID

The npsp__Gateway_Payment_ID__c field stores the WeGive transaction ID, providing a direct link back to the original transaction in WeGive. This is useful for:

• Reconciliation between systems
• Support and troubleshooting
• Audit trails
• Integration monitoring

---

​

Payment Matching & Create/Update Logic

When WeGive exports a transaction to Salesforce with payments enabled, the integration uses the following logic:

​

Step 1: Check for Existing Salesforce Payment ID

The integration first checks if the WeGive transaction already has a salesforce_payment_id stored:

• If Salesforce Payment ID exists: The integration will UPDATE the existing Payment record in Salesforce
• If no Salesforce Payment ID exists: The integration creates a NEW Payment record in Salesforce and links it to the Opportunity

​

Step 2: Link to Parent Opportunity

When creating a new Payment, the integration automatically links it to the parent Opportunity using the npe01__Opportunity__c field. This establishes the relationship between the donation commitment (Opportunity) and the actual payment transaction (Payment).

​

Why This Matters

Each transaction creates a unique Payment record linked to its Opportunity. This ensures:

• Every transaction payment is tracked separately
• Updates only modify the correct, linked Payment
• Payment details are preserved even if the Opportunity is updated
• NPSP can properly roll up payment amounts to the parent Opportunity

Important: Like Opportunities, Payments are never matched by attributes (only by stored Salesforce Payment ID). If a transaction loses its salesforce_payment_id reference in WeGive, it will create a duplicate Payment in Salesforce on the next sync.