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

# Opportunity & Payment

> Mapping between WeGive Transactions (Payments in the UI) and Salesforce Opportunities and Payments.

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

| Salesforce Field                                      | WeGive Field          | WeGive API Field                   | Direction            | Type                                               | Notes                                                                  |
| :---------------------------------------------------- | :-------------------- | :--------------------------------- | :------------------- | :------------------------------------------------- | :--------------------------------------------------------------------- |
| Name                                                  | Transaction Name      | `name`                             | Both Ways            | **Configurable**                                   | Create only; auto-generated if not provided                            |
| Amount                                                | Donation Amount       | `amount`                           | Both Ways            | **Configurable** import<br />**Hard-coded** export | Export: (amount - fee) / 100 (net amount in dollars)                   |
| CloseDate                                             | Transaction Date      | `created_at`                       | Both Ways            | **Configurable** import<br />**Hard-coded** export | Export: Formatted as Y-m-d in org timezone                             |
| Type                                                  | Transaction Type      | Dynamic                            | Export to Salesforce | **Hard-coded**                                     | 'Recurring' or 'One-Time' based on scheduled\_donation\_id             |
| LeadSource                                            | Lead Source           | Static: 'Web'                      | Export to Salesforce | **Hard-coded**                                     | Always set to 'Web'                                                    |
| RecordTypeId                                          | Record Type           | Dynamic                            | Export to Salesforce | **Hard-coded**                                     | Based on is\_tax\_deductible                                           |
| AccountId                                             | Donor Account ID      | `owner.salesforce_account_id`      | Both Ways            | **Configurable** import<br />**Hard-coded** export | Create only                                                            |
| ContactId                                             | Donor Contact ID      | `owner.salesforce_id`              | Both Ways            | **Configurable** import<br />**Hard-coded** export | Create only                                                            |
| CampaignId                                            | Campaign ID           | `campaign.salesforce_id`           | Both Ways            | **Configurable** import<br />**Hard-coded** export |                                                                        |
| npe03\_\_Recurring\_Donation\_\_c                     | Recurring Donation ID | `scheduled_donation.salesforce_id` | Both Ways            | **Configurable** import<br />**Hard-coded** export | Create only; links to recurring donation                               |
| StageName                                             | Opportunity Stage     | `stage_name`                       | Export to Salesforce | **Configurable** import<br />**Hard-coded** export | See Picklist Values section below                                      |
| npsp\_\_Tribute\_Type\_\_c                            | Tribute Type          | Static: 'Honor'                    | Export to Salesforce | **Hard-coded**                                     | Only populated if tribute exists                                       |
| npsp\_\_Honoree\_Name\_\_c                            | Tribute Name          | `tribute_name`                     | Export to Salesforce | **Hard-coded**                                     |                                                                        |
| npe01\_\_Do\_Not\_Automatically\_Create\_Payment\_\_c | Disable Auto Payment  | Static: true                       | Export to Salesforce | **Configurable** import<br />**Hard-coded** export | Literal 'true'; Create only; prevents NPSP from auto-creating payments |

## **Picklist Values**

### **StageName (Opportunity Stage)**

The integration automatically maps transaction status to Salesforce Opportunity Stage:

| WeGive Transaction Status | Default Salesforce StageName | Can Be Modified                                |
| :------------------------ | :--------------------------- | :--------------------------------------------- |
| Successful / Processing   | Closed Won                   | **Yes** - Configurable in integration settings |
| Failed                    | Closed Lost                  | **Yes** - Configurable in integration settings |
| Pending                   | Pledged                      | **Yes** - Configurable in integration settings |
| Refunded                  | Closed Lost                  | **Yes** - Configur                             |

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

| Salesforce Field                      | WeGive Field          | WeGive API Field          | Direction            | Type                                               | Notes                                                |
| :------------------------------------ | :-------------------- | :------------------------ | :------------------- | :------------------------------------------------- | :--------------------------------------------------- |
| npe01\_\_Payment\_Amount\_\_c         | Payment Amount        | `amount`                  | Both Ways            | **Configurable** import<br />**Hard-coded** export | Export: (amount - fee) / 100 (net amount in dollars) |
| npe01\_\_Payment\_Date\_\_c           | Payment Date          | `created_at`              | Both Ways            | **Configurable** import<br />**Hard-coded** export | Export: Formatted date                               |
| npe01\_\_Payment\_Method\_\_c         | Payment Method        | `source_type`             | Export to Salesforce | **Configurable** import<br />**Hard-coded** export | See Picklist Values section                          |
| npe01\_\_Paid\_\_c                    | Payment Status        | Dynamic                   | Export to Salesforce | **Configurable** import<br />**Hard-coded** export | Based on transaction status                          |
| npe01\_\_Opportunity\_\_c             | Opportunity ID        | `salesforce_id`           | Export to Salesforce | **Configurable** import<br />**Hard-coded** export | Create only; links to Opportunity                    |
| npsp\_\_Batch\_Number\_\_c            | Payout ID             | `payout_id`               | Export to Salesforce | **Configurable** export                            |                                                      |
| npsp\_\_Gateway\_Payment\_ID\_\_c     | WeGive Transaction ID | `id`                      | Export to Salesforce | **Configurable** export                            | Create only                                          |
| npsp\_\_Total\_Transaction\_Fees\_\_c | Transaction Fee       | `fee_amount`              | Export to Salesforce | **Configurable** export                            |                                                      |
| npsp\_\_Donor\_Cover\_Amount\_\_c     | Fee Covered Amount    | `fee_covered_amount`      | Export to Salesforce | **Configurable** export                            | Create only                                          |
| npsp\_\_Card\_Last\_4\_\_c            | Card Last 4 Digits    | `paymentMethod.last_four` | Export to Salesforce | **Configurable** export                            | Create only; for credit/debit cards                  |
| npsp\_\_Card\_Network\_\_c            | Card Network          | `paymentMethod.issuer`    | Export to Salesforce | **Configurable** export                            | Create only; e.g., Visa, Mastercard                  |

## **Picklist Values**

### **npe01\_\_Payment\_Method\_\_c (Payment Method)**

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

| WeGive Payment Type | Default Salesforce Payment Method | Can Be Modified                                   |
| :------------------ | :-------------------------------- | :------------------------------------------------ |
| card                | Credit Card                       | **Yes** - Configurable via payment method mapping |
| bank\_account (ACH) | ACH/EFT                           | **Yes** - Configurable via payment method mapping |
| paypal              | PayPal                            | **Yes** - Configurable via payment method mapping |
| venmo               | Venmo                             | **Yes** - Configurable via payment method mapping |
| check               | Check                             | **Yes** - Configurable via payment method mapping |
| cash                | Cash                              | **Yes** - Configurable via payment method mapping |
| stock               | Stock                             | **Yes** - Configurable via payment method mapping |
| wire                | Wire Transfer                     | **Yes** - Configurable via payment method mapping |
| other               | Other                             | **Yes** - Configurable via payment method mapping |

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

| Transaction Status | npe01\_\_Paid\_\_c Value |
| :----------------- | :----------------------- |
| successful         | true                     |
| refunded           | true                     |
| pending            | false                    |
| failed             | false                    |

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.