​

Salesforce Object: wegive__Payout__c (custom object)\

WeGive Model: Payout

​

Overview

This document describes how payout data syncs between WeGive and Salesforce. Payouts represent the transfer of funds from payment processors (like Stripe) to the organization’s bank account. They include detailed financial summaries showing donation income, fees, refunds, and net amounts deposited. Note: This feature requires the WeGive managed package to be installed in Salesforce, which includes the custom wegive__Payout__c object. Organization-Specific Implementation: Some organizations may use a custom payout object name instead of the standard wegive__Payout__c. The field mappings and structure remain the same, but the object API name may differ based on the organization’s setup.

---

​

How Payout Data Syncs

​

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

• Hard-coded - Built into the integration logic and cannot be changed

---

​

Sync Triggers

​

From WeGive to Salesforce (Export)

Payout data is exported from WeGive to Salesforce when:

• Payout Created: A new payout is received from the payment processor
• Payout Updated: An existing payout is modified (e.g., payout reconciled, fees adjusted)

The export happens automatically after the create or update action in WeGive.

​

From Salesforce to WeGive (Import)

Payout data is typically NOT imported from Salesforce to WeGive because:

• Payouts originate from payment processors (Stripe, PayPal, etc.)
• WeGive is the system of record for payout data
• Financial data flows from processor → WeGive → Salesforce

However, if payouts are modified in Salesforce, updates would sync based on standard sync triggers.

---

​

Sync Process Overview

​

Payout-Level Synchronization

WeGive syncs payouts at the individual payout level, including comprehensive financial summaries that break down the components of each deposit. This includes donation income, fees, refunds, disputes, and net deposit amounts.

​

Pushing Data to Salesforce

When a Payout is created or updated in WeGive, the integration:

1. Generates Financial Summary:
   • Calculates total donation income
   • Separates tax-deductible donations from service revenue
   • Sums up all fees (processing fees, platform fees, etc.)
   • Calculates net refunds and disputes
   • Determines balance released and reserved amounts
2. Compiles Deposit Information:
   • Tracks individual deposits if payout was split across multiple transfers
   • Records deposit amounts (up to 2 deposits tracked)
   • Stores deposit dates and references
3. Creates or Updates Record:
   • If payout has a salesforce_id: UPDATE the existing Payout record
   • If no salesforce_id: CREATE a new Payout record

---

​

Complete Field Mapping

​

Important Notes

​

Payout Summary Generation

WeGive generates a comprehensive financial summary for each payout by analyzing all transactions included in the payout. This summary breaks down: Income Categories:

• Total Donations: Tax-deductible gifts (gross amount and fees)
• Service Revenue: Non-deductible income like ticket sales (gross amount and fees)

Deductions:

• Donation Refunds: Refunded tax-deductible gifts
• Service Revenue Refunds: Refunded non-deductible income
• Disputes/Chargebacks: Disputed or charged-back transactions
• Total Fees: Processing fees, platform fees, etc.
• Other Fees: Miscellaneous fee entries

Balance Movements:

• Balance Released: Funds released from processor reserve
• Balance Reserved: Funds held back in processor reserve

​

Amount Conversion

All amounts require conversion between systems:

• WeGive: Stores amounts in cents as integers (e.g., 50000 = $500.00)
• Salesforce: Stores amounts in dollars as decimals (e.g., 500.00)
• On export: WeGive divides by 100 to convert cents to dollars

​

Multiple Deposits

Some payouts are split across multiple bank deposits:

• Single Deposit: If no split, Deposit_1_Amount__c equals the total payout amount
• Split Deposits: If split, both Deposit_1_Amount__c and Deposit_2_Amount__c are populated
• Maximum of 2 deposits are tracked in this integration
• If more than 2 deposits exist, additional deposits are not separately tracked

​

Payment Processor Information

The WeGive_Processor__c field combines multiple pieces of information:

• Payment processor name (e.g., “Stripe”, “PayPal”)
• WeGive payout ID
• Processor reference ID
• Format: [processor] - [payout_id] - [reference]

​

Transaction Count

The integration counts all transactions associated with the payout, including:

• Successful donations
• Refunds
• Fees
• Disputes/chargebacks
• Any other transaction types included in the payout

​

Reserved Balance (Negative Values)

The Balance_Reserved__c field is stored as a negative value:

• Represents funds being held back by the processor
• Calculated as abs(Balance Reserve.net) * -1
• This ensures the field displays correctly as a deduction in reports

---

​

Payout Matching & Create/Update Logic

​

When WeGive Exports a Payout to Salesforce

Step 1: Generate Financial Summary

• Analyze all transactions in the payout
• Calculate totals for each category (donations, fees, refunds, etc.)
• Compile deposit information

Step 2: Check for Existing Salesforce Payout ID

• If the WeGive payout has a salesforce_id: The integration UPDATES the existing Payout record in Salesforce
• If no salesforce_id exists: The integration CREATES a new Payout record in Salesforce

Step 3: Compile and Send Payload

• Convert all amounts from cents to dollars
• Format dates appropriately
• Include transaction count and deposit details
• Send to Salesforce

​

When Salesforce Exports a Payout to WeGive

This is not a standard workflow since payouts originate in payment processors and flow through WeGive. However, if implemented: Step 1: Check for Existing WeGive Payout

• The integration would search for an existing payout by salesforce_id
• If found, it would update that payout
• If not found, it would create a new payout (rare scenario)

​

Why This Matters

This matching logic ensures:

• Each WeGive payout maps to exactly one Salesforce Payout record
• Financial summaries are comprehensive and accurate
• Deposit information is properly tracked
• Updates to payout reconciliation sync correctly

---

​

Required Fields

For WeGive to Salesforce:

• wegive__Payout_Date__c (Payout Date)
• wegive__WeGive_Payout_Id__c (WeGive Payout ID)
• wegive__Number_of_Transactions__c (Transaction Count)

All financial summary fields are strongly recommended for complete payout tracking, though technically optional in Salesforce.

​

Usage in WeGive

Payouts in WeGive are used for:

• Financial Reconciliation: Match bank deposits to transaction batches
• Fee Analysis: Understand processing costs and fee structures
• Revenue Reporting: Break down income by type (donations vs. service revenue)
• Cash Flow Management: Track when funds are actually received
• Dispute Tracking: Monitor chargebacks and disputed transactions
• Accounting Integration: Export payout data to accounting software
• Processor Comparison: Compare payout structures across different processors

---

​

Usage in Salesforce

Payouts in Salesforce are used for:

• Financial Reporting: Create dashboards showing deposit trends
• Reconciliation: Match Salesforce records to bank statements
• Fee Analysis: Analyze processing costs over time
• Budget Planning: Understand net revenue after fees
• Audit Trail: Maintain records of all financial transfers
• Executive Reporting: Summarize financial performance
• Integration: Connect to accounting or ERP systems

---

​

Understanding Hard-coded Mappings

All payout field mappings are hard-coded because:

• Financial calculations must be consistent and reliable
• The payout summary structure is standardized across organizations
• Custom fields on payouts are rarely needed
• The integration performs complex calculations that require specific logic

---

​

Financial Summary Categories Explained

​

Total Donations

• Gross: Total amount of tax-deductible gifts before fees
• Fees: Processing fees charged on these donations
• Net: Amount after fees (Gross - Fees)

​

Service Revenue

• Gross: Total amount of non-deductible income (event tickets, merchandise, etc.)
• Fees: Processing fees charged on this revenue
• Net: Amount after fees (Gross - Fees)

​

Refunds

• Donation Refunds: Refunded tax-deductible gifts (reduces total donations)
• Service Revenue Refunds: Refunded service revenue (reduces service revenue)

​

Fees

• Donation Fees: Processing fees specifically on donations
• Service Revenue Fees: Processing fees specifically on service revenue
• Other Fees: Miscellaneous fees not directly tied to transactions

​

Disputes/Chargebacks

• Disputed: Total amount of disputed transactions and chargebacks
• Reduces net payout amount
• May include dispute fees

​

Balance Movements

• Balance Released: Previously reserved funds now released
• Balance Reserved: Funds held back by processor for risk management

---

​

Best Practices

1. Reconcile regularly - Match payouts to bank statements monthly
2. Review fees - Monitor processing costs and negotiate rates when possible
3. Track disputes - Investigate chargebacks promptly to reduce losses
4. Document split deposits - Note why payouts were split if applicable
5. Monitor reserves - Understand why funds are being held and when they’ll release
6. Archive payout records - Maintain records for accounting and audit purposes
7. Compare processors - Analyze payout summaries to evaluate processor performance
8. Set up alerts - Monitor for unusual payout patterns or large fee amounts
9. Train finance team - Ensure staff understand payout components and terminology
10. Coordinate with accounting - Ensure payout data flows properly to accounting systems

---

​

Troubleshooting

Payout not syncing:

• Verify the WeGive managed package is installed
• Check that payout has been created/modified in WeGive
• Ensure integration has access to the payout object (may be custom named)

Amounts don’t match bank statement:

• Verify all amounts are converted correctly (cents to dollars)
• Check for split deposits - sum both deposit amounts
• Review balance released/reserved - these affect net amount
• Account for all fees, refunds, and disputes in the summary

Transaction count incorrect:

• Verify all transactions in the payout period are included
• Check that refunds, fees, and disputes are counted
• Ensure the payout summary includes all transaction types

Missing deposit information:

• If only one deposit, only Deposit_1_Amount__c is populated
• Verify deposit records exist in WeGive
• Check that deposits are linked to the correct payout

Fees don’t match processor statement:

• Verify fee calculation includes all fee types
• Check that donation fees and service revenue fees are separated correctly
• Review “Other Fees” category for miscellaneous charges

Balance reserved showing wrong sign:

• Reserved amounts should be negative (deductions)
• Verify calculation: abs(amount) * -1
• This ensures proper display in Salesforce reports

Custom object name different:

• Some organizations use custom payout object names
• Verify the correct object API name in the integration settings
• Field mappings remain the same regardless of object name

---

​

Organization-Specific Notes

​

Standard Implementation

Most organizations use wegive__Payout__c as the Salesforce object name with the standard WeGive field naming convention (wegive__Field_Name__c).

​

Custom Implementation Example

Some organizations (e.g., Washington Animal Hospital) use a custom object name like WeGive_Payouts__c with custom field naming like Field_Name__c (without the wegive__ prefix). The integration handles both implementations - the field mapping logic remains the same, only the object and field API names differ based on the organization’s configuration.