Data Mapping
Opportunity & Payment
Mapping between WeGive Transactions (Payments in the UI) and Salesforce Opportunities and Payments.
Opportunity and Payment
The Opportunity and Payment mapping between WeGive and Salesforce is a fundamental component of the integration, enabling seamless synchronization of donation transactions and payment information between the two platforms. This mapping ensures that all aspects of donations, from basic transaction details to complex payment processing, are properly tracked and maintained across both systems.Key Concepts
The integration between WeGive Transactions and Salesforce Opportunities/Payments is designed to provide a comprehensive solution for managing donation transactions. Understanding these key concepts is essential for effective implementation and usage.Integration Overview
- Transaction Representation: WeGive Transactions are represented by a combination of Opportunities and Payments in Salesforce.
- Payment-Level Sync: Integration syncs at the Payment level primarily, not the Opportunity level.
- Multiple Payments: Single Opportunity with multiple Payments results in multiple Transactions in WeGive.
- Data Sources: Pulls data from both Opportunity (tax-deductible status) and Payment objects.
Sync Behavior
- Bi-directional synchronization:
- Real-time updates
- Transaction tracking
- Payment processing
- Status monitoring
Dependencies
- Donor synchronization
- Campaign tracking
- Fund allocation
- Payment processing
- Soft credit handling
Sync Process Overview
Payment-Level Synchronization
WeGive syncs primarily on the Payment object level in Salesforce, even though it represents WeGive Transactions as Opportunities and pulls data from the Opportunity record. This means that if a single Opportunity in Salesforce has multiple associated Payments, WeGive will pull each of those Payments in and represent them as separate, individual Transaction records in WeGive. WeGive pulls all the relationships like Campaign, Fund, Recurring Donation, Contact, and Account from the Opportunity, but it creates distinct Transaction records in WeGive for each Payment it finds.Pulling Data from Salesforce
When pulling data from Salesforce, WeGive queries Payments where thenpe01__Paid__c field is true and the last modified date on either the Payment itself or the associated Opportunity is within the specified time bounds. WeGive ignores Opportunities that are marked unpaid when pulling. The integration pulls data from both the Payment record (such as the Payment ID and Amount) and the associated Opportunity to get additional context, including the StageName, RecordTypeId, and relationship data.
Upon importing this data, WeGive attempts to find an existing WeGive Transaction record matching the Salesforce Payment ID. If an existing Transaction is found, it’s updated; if not, a new Transaction record is created in WeGive. The relationship data pulled from the Opportunity (like Contact ID, Account ID, Campaign ID, Recurring Donation ID, Pledge ID) is used to associate the WeGive Transaction with the correct donor, campaign, fund, recurring donation, and pledge records in WeGive.
Pushing Data to Salesforce
When a Transaction (donation) originates or is updated in WeGive and needs to be sent to Salesforce, WeGive compiles a payload specifically for the Salesforce Payment object. This payload includes default data as well as data based on user-defined mapping rules. Before pushing the Payment, WeGive ensures that necessary related records like the Donor, Campaign, and Fund exist in Salesforce. For recurring transactions, WeGive attempts to match recurring donation transactions to open pledged installments in Salesforce to avoid duplicates. The mapping includes logic to hardcode the payment status as ‘true’ and Opportunity lead source as ‘Web’. WeGive will insert a new Payment or update an existing one in Salesforce, saving the Salesforce Payment ID back to WeGive.Field Mappings
The field mappings between WeGive Transactions and Salesforce Opportunities/Payments are designed to ensure comprehensive data synchronization. These mappings cover all essential transaction and payment information, from basic details to complex processing rules.Opportunity Field Mappings
| Salesforce Field | WeGive Field | Direction | Create Only | Default Mapping | Notes |
|---|---|---|---|---|---|
Name | name | Both | Yes | Yes | Used for naming the Opportunity record. Auto-generated or custom. |
Amount | amount | Both | No | Yes | Donation amount (converted from cents) |
AccountId | owner.salesforce_account_id | Both | Yes | Yes | Links the Opportunity to the Account (Household or Company) in Salesforce. |
CloseDate | created_at | Both | No | Yes | Date is formatted for Salesforce date fields and is based on the transaction date in WeGive (date initiated). |
CampaignId | campaign.salesforce_id | Both | No | Yes | Links the Opportunity to the Campaign in Salesforce. |
ContactId | owner.salesforce_id | Both | Yes | Yes | Links the Opportunity to the Contact (Individual) in Salesforce. |
npe03__Recurring_Donation__c | scheduled_donation.salesforce_id | Both | Yes | Yes | Links the Opportunity to the Recurring Donation in Salesforce. |
StageName | stage_name | Export | No | Yes | Imported based on SF StageName. Exported based on WeGive Transaction status, mapped to SF StageName based on integration settings. |
npe01__Do_Not_Automatically_Create_Payment__c | TRUE | Export | Yes | Yes | Hardcoded to true when creating a new Opportunity from WeGive to prevent Salesforce from auto-creating payments. |
Type | Derived from WeGive Transaction | Export | No | No | ’Recurring’ if scheduled_donation_id exists, else ‘One-Time’ |
LeadSource | 'Web' | Export | Yes | Yes | Hardcoded value applied during insert. |
npsp__Tribute_Type__c | Derived from WeGive Transaction | Export | Yes | No | ’Honor’ if tribute exists |
npsp__Honoree_Name__c | tribute_name | Export | Yes | No | Populated if the transaction is a tribute gift in WeGive. |
is_tax_deductible | is_tax_deductible | Both | No | No | Pulled during import based on the Salesforce Opportunity RecordTypeId matching configured ‘service revenue’ types. |
hidden | hidden | Both | No | No | Pulled during import based on the Salesforce Opportunity RecordTypeId matching configured ‘hidden’ types. |
Payment Field Mappings
| Salesforce Field | WeGive Field | Direction | Create Only | Default Mapping | Notes |
|---|---|---|---|---|---|
npe01__Payment_Date__c | created_at | Both | No | Yes | Date is formatted for Salesforce date fields. |
npe01__Payment_Method__c | source_type | Both | No | Yes | Mapped based on WeGive’s internal payment method type. |
npe01__Paid__c | TRUE | Export | No | Yes | Hardcoded to true when pushing payments to Salesforce. |
npe01__Payment_Amount__c | amount | Both | No | Yes | Donation amount |
npe01__Opportunity__c | salesforce_id | Export | Yes | Yes | Links the Payment to the Opportunity. Omitted during updates. |
npsp__Batch_Number__c | payout_id | Export | No | Yes | May be omitted in legacy integrations. |
npsp__Gateway_Payment_ID__c | id | Export | Yes | Yes | May be omitted in legacy integrations. |
npsp__Total_Transaction_Fees__c | fee_amount | Export | Yes | Yes | May be omitted in legacy integrations. |
npsp__Donor_Cover_Amount__c | Derived from WeGive Transaction | Export | No | No | Calculated based on whether the donor covered fees. May be omitted in legacy integrations. |
Payment Method Mappings
| WeGive Type | Salesforce Value |
|---|---|
| card | Credit Card |
| bank | ACH |
| paypal | PayPal |
| check | Check |
| cash | Cash |
Stage Name Mappings
| WeGive Status | Salesforce Stage |
|---|---|
| SUCCESS/PROCESSING | Configurable (stage_success) |
| PENDING | Configurable (stage_pending) |
| REFUNDED | Configurable (stage_refunded) |
| FAILED | Configurable (stage_failed) |
Important Notes
Understanding these important aspects of the Opportunity & Payment integration is crucial for successful implementation and ongoing management.Managed Package Details (if installed)
- Standard object names (must be configured)
Opportunitynpe01__OppPayment__c
- Package source: WeGive Managed Package
- Installation is required for functionality
- Custom fields are included
- Field-level security must be set
- User permissions must be configured
Field Considerations
- Required fields must be mapped
- Custom fields can be added
- Field types must match
- Validation rules apply
- Default values are supported
Best Practices
Following these best practices will help ensure a smooth and successful Opportunity & Payment integration:Data Management
- Regular data validation
- Monitor sync status
- Check for duplicates
- Verify field mappings
- Review error logs
Integration Configuration
- Test in sandbox first
- Verify permissions
- Check field security
- Monitor performance
- Regular maintenance
Troubleshooting
- Check sync logs
- Verify connections
- Review error messages
- Test field mappings
- Contact support if needed
Common Scenarios
Understanding these common scenarios will help you effectively manage Opportunities and Payments across both platforms:New Transaction Creation
- Create transaction in WeGive
- Sync to Salesforce
- Process payment
- Update status
- Monitor sync status
Payment Processing
- Process payment
- Update transaction
- Track status
- Monitor sync
- Handle updates
Transaction Updates
- Modify transaction details
- Update payment info
- Change status
- Adjust amounts
- Sync changes