​

Donation Mapping

This document provides comprehensive mapping details between WeGive transaction objects and Planning Center donation records, including batch processing, fund designations, and payment source management.

​

Overview

Planning Center’s Giving module uses the Donation object to represent individual gifts, organized into Batches for accounting purposes. Each donation can have multiple Designations for fund allocation and links to PaymentSource objects for payment tracking. WeGive maps these to the Transaction object with appropriate batch organization.

​

Core Donation Mapping

​

Primary Fields

WeGive Field	Planning Center Field	Type	Required	Transformation
id	Correlation ID	String	No	Stored in WeGive planning_center_id
amount	amount_cents	Integer	Yes	Direct cents mapping
created_at	created_at	DateTime	Yes	ISO 8601 format
owner (donor_id)	person	Reference	Yes	Person object reference
status	Status indicator	String	No	Transaction status mapping
planning_center_id	id	String	No	Donation ID correlation

​

Extended Fields

WeGive Field	Planning Center Field	Transformation	Notes
currency	currency	Direct mapping	Defaults to USD
reference	Internal reference	Transaction tracking	WeGive transaction ID
memo	memo	Direct mapping	Internal notes
fee_amount	fee_cents	Direct cents mapping	Processing fees

​

Batch Processing Integration

​

Daily Batch Organization

Batch Creation Logic:

• Donations grouped by transaction date (not processing date)
• Daily batch format: “WeGive Import - [YYYY-MM-DD]”
• All WeGive transactions for a specific day included in single batch
• Automatic batch creation during push operations

Batch Object Structure:

WeGive Data	Planning Center Field	Transformation	Notes
Transaction date	Batch.description	Date-based naming	”WeGive Import - 2024-01-15”
Daily total	Batch.total_cents	Sum of all donations	Batch total validation
Transaction count	Batch.donations_count	Count of donations	Batch completeness check
Processing time	Batch.committed_at	Batch finalization	Automatic commitment

​

Batch Processing Workflow

Batch Creation Process:

1. Group Transactions: Organize WeGive transactions by date
2. Create Batch: Create Planning Center batch with descriptive name
3. Add Donations: Create donation records within batch
4. Validate Totals: Verify batch totals match transaction sums
5. Commit Batch: Finalize batch for accounting purposes
6. Error Handling: Rollback entire batch if any donation fails

Batch Status Management:

• Uncommitted: Batch created but not finalized
• Committed: Batch finalized and ready for accounting
• Failed: Batch processing failed, requires attention
• Rolled Back: Batch reversed due to errors

​

Fund Designation Mapping

​

Single Fund Designation

Simple Fund Assignment:

• WeGive transaction with single fund creates one Designation
• Designation amount equals full transaction amount
• Fund reference links to Planning Center fund object
• Default fund used when no specific designation provided

Designation Object Structure:

WeGive Field	Planning Center Field	Transformation	Notes
amount	Designation.amount_cents	Direct cents mapping	Full transaction amount
fund_id	Designation.fund	Fund object reference	Planning Center fund
Transaction ID	Designation.donation	Donation reference	Parent donation

​

Multiple Fund Designations

Split Fund Handling:

• WeGive fund allocations create multiple Designation objects
• Each allocation creates separate designation with specific amount
• Designation amounts must sum to total donation amount
• All designations linked to same donation record

Split Designation Example:

• WeGive transaction: $100 split between two funds ($60 + $40)
• Creates one Donation object for $100
• Creates two Designation objects: $60 to Fund A,$40 to Fund B
• Validation ensures $60 +$40 = $100 total

​

Default Fund Assignment

Fund Assignment Priority:

1. Specific Fund: Use designated fund from WeGive transaction
2. Default Fund: Use configured default fund when no designation
3. General Fund: Fall back to organization’s general fund
4. Error Handling: Transaction fails if no valid fund available

Default Fund Configuration:

• Default fund ID stored in integration settings
• Must be active and valid Planning Center fund
• Used for transactions without specific fund designation
• Prevents donation processing failures

​

Payment Source Management

​

WeGive Payment Source

Unified Payment Source Strategy:

• All WeGive transactions use single “WeGive” payment source
• Payment source created automatically during setup
• Original payment method preserved in transaction metadata
• Simplifies Planning Center payment source management

Payment Source Object:

WeGive Data	Planning Center Field	Transformation	Notes
”WeGive”	PaymentSource.name	Fixed value	All transactions use this source
Payment method details	PaymentSource.description	Method summary	Original payment method info
Electronic	PaymentSource.type	Fixed type	Categorization for reporting

​

Payment Method Preservation

Original Payment Method Tracking:

• WeGive payment method stored in donation metadata
• Credit card, ACH, check details preserved
• Payment method accessible for detailed reporting
• Transaction-level payment information maintained

Payment Method Types:

WeGive Source Type	Preserved Information	Planning Center Usage
card	Card type, last 4 digits	”WeGive” payment source
bank	Bank name, account type	”WeGive” payment source
check	Check number, date	”WeGive” payment source
cash	Cash designation	”WeGive” payment source
other	Method description	”WeGive” payment source

​

Data Transformation

​

Donation Creation Processing

WeGive to Planning Center Donation:

1. Validate Transaction: Ensure amount, date, and donor are valid
2. Resolve Person: Link to existing Planning Center person or create new
3. Determine Batch: Assign to daily batch or create new batch
4. Create Donation: Create donation record with transaction details
5. Create Designations: Create fund allocation designations
6. Link Payment Source: Assign to “WeGive” payment source
7. Store Correlation: Save Planning Center donation ID

Amount and Currency Processing:

• WeGive amounts stored in cents, mapped directly to Planning Center
• Currency code preserved (defaults to USD)
• Fee amounts mapped to separate fee fields
• Amount validation ensures positive values

​

Date and Time Handling

Date Processing:

• WeGive transaction created_at mapped to donation created_at
• Date used for batch organization (by date, not datetime)
• Timezone considerations for accurate date grouping
• Historical transaction dating preserved

​

Sync Operations

​

Push Operation (WeGive → Planning Center)

​

Create New Donation

Process:

1. Batch Determination: Find or create daily batch for transaction date
2. Person Validation: Ensure donor exists in Planning Center
3. Donation Creation: Create donation with amount, date, and person
4. Designation Creation: Create fund allocation designations
5. Payment Source Assignment: Link to “WeGive” payment source
6. Batch Update: Update batch totals and counts
7. Correlation Storage: Store donation ID for future updates

​

Batch Commitment

Process:

1. Batch Validation: Verify all donations in batch are valid
2. Total Verification: Confirm batch total matches sum of donations
3. Designation Validation: Ensure all designations are properly assigned
4. Batch Commitment: Finalize batch for accounting
5. Error Handling: Rollback entire batch if any issues detected

​

Pull Operation (Planning Center → WeGive)

​

Import Donation

Process:

1. Donation Retrieval: Get donation with related data (person, designations)
2. Person Resolution: Map Planning Center person to WeGive donor
3. Amount Processing: Convert amount and handle currency
4. Fund Mapping: Map designations to WeGive funds
5. Transaction Creation: Create or update WeGive transaction
6. Correlation Storage: Store donation ID for bidirectional sync

​

Batch Information Processing

Batch Data Import:

• Batch information preserved in transaction metadata
• Batch date and description accessible for reporting
• Batch commitment status tracked
• Historical batch organization maintained

​

Recurring Donation Integration

​

Recurring Gift Relationship

Recurring Donation Tracking:

• Individual donations linked to recurring gift schedules
• Sequence number tracking within recurring series
• Schedule modification impact on individual donations
• Automated recurring donation processing

Recurring Gift Coordination:

• WeGive scheduled donations mapped to Planning Center recurring gifts
• Individual transactions created from recurring gift schedules
• Payment method and fund consistency across recurring series
• Schedule changes reflected in individual donations

​

Validation and Error Handling

​

Donation Validation

Required Field Validation:

• Amount must be positive value
• Donation date is required and reasonable
• Person reference must exist and be valid
• At least one fund designation required

Business Rule Validation:

• Donation amount matches sum of designations
• Fund references are active and valid
• Person is not marked as deceased
• Batch totals are accurate

​

Error Handling

Common Donation Errors:

• Invalid person reference (donor doesn’t exist)
• Missing or inactive fund designation
• Amount validation failures (negative, zero)
• Batch processing errors

Error Recovery:

• Person Creation: Create Planning Center person for missing donors
• Default Fund Assignment: Use default fund for invalid designations
• Batch Rollback: Reverse entire batch for critical errors
• Manual Review: Queue problematic donations for review

​

Batch Error Handling

Batch-Level Errors:

• Single donation failure doesn’t fail entire batch
• Critical errors trigger full batch rollback
• Partial batch processing with error isolation
• Comprehensive error logging for troubleshooting

​

Performance Optimization

​

Batch Processing Efficiency

Daily Batch Strategy:

• Optimize API usage through batch organization
• Reduce individual API calls for donations
• Efficient batch commitment process
• Background processing for large batches

Processing Optimization:

• Person lookup optimization before donation creation
• Fund validation caching
• Batch total calculation efficiency
• Payment source reuse across donations

​

API Usage Optimization

Request Minimization:

• Batch creation with multiple donations
• Efficient designation creation
• Combined person and donation validation
• Optimized fund and payment source references

​

Integration with Accounting

​

Financial Reporting Integration

Batch-Based Reporting:

• Daily batches provide accounting structure
• Batch totals enable financial reconciliation
• Fund designation reporting
• Payment source categorization

Audit Trail Maintenance:

• Complete donation history preservation
• Batch processing logs
• Fund designation tracking
• Payment source attribution

​

Reconciliation Support

Data Reconciliation:

• Batch total validation
• Fund allocation verification
• Payment source consistency
• Person relationship integrity

This comprehensive donation mapping ensures accurate financial transaction synchronization between WeGive and Planning Center while maintaining proper accounting structure and audit trails for effective church financial management.