​

Integration Nuances

This document outlines important behaviors, limitations, and considerations when using the WeGive Planning Center integration, including specific features of the People and Giving modules.

​

Authentication Behaviors

​

OAuth 2.0 Flow

Authentication Process:

• Initial OAuth authorization redirects to Planning Center
• User grants permission for ‘people giving’ scopes
• Authorization code exchanged for access and refresh tokens
• Automatic token refresh without user intervention

Token Management:

• Access tokens automatically refreshed before expiration
• Refresh tokens stored securely for ongoing authentication
• Failed token refresh triggers re-authorization flow
• Token scope limited to People and Giving modules only

​

Legacy Authentication

Basic Auth Process:

• Uses Application ID and Personal Access Token
• Direct API authentication without OAuth flow
• Manual token rotation required for security
• Same scope access as OAuth (people and giving)

Migration Considerations:

• OAuth 2.0 recommended for new implementations
• Legacy auth continues to work for existing setups
• Migration to OAuth available without data loss

​

Data Flow Behaviors

​

Daily Batch Processing

WeGive Import Batches:

• Daily batches created automatically at 8:01 AM
• Batch name format: “WeGive Import - [Date]”
• All WeGive transactions for the day included in single batch
• Automatic batch commitment after successful processing

Batch Processing Logic:

• Transactions grouped by donation date, not processing date
• Missing transaction batches detected and created automatically
• Failed batch processing triggers rollback of entire batch
• Batch status tracked for audit and troubleshooting

​

Fund Assignment Logic

Priority Order for Fund Assignment:

1. Specific Fund: Use designated fund from WeGive transaction
2. Default Fund: Fall back to configured default fund
3. Fund Creation: Create new fund if specified fund doesn’t exist
4. General Fund: Use organization’s general fund as final fallback

Fund Visibility Handling:

• Hidden funds in Planning Center marked as deleted in WeGive
• Fund visibility changes sync bidirectionally
• Fund creation requires active status in Planning Center
• Fund deletion preserves historical transaction references

​

Contact Management Behaviors

​

Person Record Matching

Matching Strategy (in order of preference):

1. Planning Center ID: Exact match using stored correlation ID
2. Email Address: Primary email address matching
3. Name Matching: Full name comparison for individuals
4. Create New: When no match found

Contact Information Handling:

• Primary email address mapped to main email field
• Additional email addresses stored as secondary contacts
• Phone numbers categorized by type (mobile, home, work)
• Address information synchronized with full geographic data

​

Family and Household Relationships

Family Coordination:

• Individual person records maintained separately
• Family relationships preserved in Planning Center structure
• Household addresses coordinated across family members
• Contact preferences managed at individual level

​

Payment Source Management

​

WeGive Payment Source

Single Payment Source Strategy:

• All WeGive transactions use “WeGive” payment source in Planning Center
• Payment method details preserved in transaction metadata
• Simplifies Planning Center payment source management
• Enables unified reporting across all WeGive payment types

Payment Method Mapping:

• Credit cards, ACH, checks all attributed to “WeGive” source
• Original payment method preserved in transaction details
• Payment source creation automatic during initial setup
• Payment source reused for all subsequent transactions

​

API Rate Limiting and Performance

​

Planning Center API Limits

Rate Limiting Rules:

• 70 requests per 20-second window
• Automatic rate limit detection and compliance
• Request queuing during rate limit periods
• Intelligent batching to optimize API usage

Performance Optimization:

• Incremental sync for efficiency (only changed data)
• Batch operations for bulk data processing
• Request optimization to minimize API calls
• Background job processing for time-intensive operations

​

Large Data Set Handling

Initial Sync Considerations:

• Large datasets may require extended processing time
• Progress tracking available for long-running sync operations
• Checkpoint system for resuming interrupted syncs
• Memory optimization for processing large volumes

​

Error Handling and Recovery

​

Automatic Error Recovery

Retry Logic:

• Failed API requests automatically retried up to 3 times
• Exponential backoff prevents API overload
• Different retry strategies for different error types
• Manual retry options available for persistent failures

Batch Error Handling:

• Single transaction failure doesn’t fail entire batch
• Failed transactions quarantined for manual review
• Batch rollback capability for critical errors
• Comprehensive error logging for troubleshooting

​

Common Error Scenarios

Authentication Errors:

• Token expiration handled automatically with refresh
• Scope permission errors logged with clear messages
• Invalid credentials trigger re-authentication flow
• Network connectivity issues handled with retries

Data Validation Errors:

• Missing required fields cause transaction rejection
• Invalid fund IDs trigger default fund assignment
• Duplicate detection prevents record conflicts
• Data format errors logged with specific field information

​

Sync Timing and Scheduling

​

Daily Processing Schedule

Automated Operations:

• 8:01 AM: Daily batch generation for previous day’s transactions
• 8:15 AM: Pull sync for updated Planning Center data
• Continuous: Real-time processing for immediate updates (when enabled)
• Weekly: Comprehensive data validation and cleanup

Manual Sync Options:

• Full sync available for complete data refresh
• Incremental sync for recent changes only
• Specific date range sync for historical data
• Test sync for configuration validation

​

Incremental vs. Full Sync

Incremental Sync Benefits:

• Faster processing for daily operations
• Lower API usage and better performance
• Focuses on recently changed data only
• Maintains sync efficiency for ongoing operations

Full Sync Use Cases:

• Initial integration setup
• Data quality audits and cleanup
• Recovery from extended outages
• Configuration changes requiring complete refresh

​

Fund and Designation Behaviors

​

Fund Creation and Management

Automatic Fund Creation:

• Missing funds created automatically when referenced
• Fund names synchronized between systems
• Fund descriptions and metadata preserved
• Fund status (active/inactive) coordinated

Fund Designation Logic:

• Split designations supported for multiple funds
• Designation amounts validated against transaction total
• Fund allocation percentages calculated automatically
• Undesignated amounts assigned to default fund

​

Recurring Gift Coordination

Recurring Gift Processing:

• Planning Center recurring gifts linked to WeGive scheduled donations
• Recurring gift schedules synchronized bidirectionally
• Individual gifts created from recurring gift schedules
• Schedule modifications reflected in both systems

​

Data Quality and Validation

​

Contact Information Validation

Email Validation:

• Email format validation before sync
• Duplicate email detection within organization
• Invalid emails logged but don’t prevent contact creation
• Email preference coordination between systems

Address Standardization:

• Address formatting normalized for consistency
• Geographic data validation where possible
• International address support with country codes
• Address type designation (home, work, mailing)

​

Financial Data Validation

Transaction Validation:

• Amount validation ensures positive values
• Date validation prevents future-dated transactions
• Fund validation confirms fund exists and is active
• Currency validation for international organizations

​

Reporting and Analytics Integration

​

Financial Reporting Coordination

Batch Reporting:

• Daily batch summaries for accounting reconciliation
• Transaction counts and totals for validation
• Fund allocation reports for designation tracking
• Error reports for data quality monitoring

Donor Analytics:

• Giving history synchronized between systems
• Donor engagement metrics coordinated
• Contact communication history preserved
• Giving pattern analysis supported

​

Security and Compliance

​

Data Privacy Considerations

Information Sharing:

• Only necessary data synchronized between systems
• Contact preferences respected in both platforms
• Data retention policies coordinated
• Privacy compliance maintained across integration

Access Control:

• Integration access limited to configured scopes
• API permissions validated during setup
• Audit logs maintained for all sync operations
• Security monitoring for unusual activity patterns

​

Performance Monitoring

​

Integration Health Checks

Automated Monitoring:

• Daily batch processing success rates
• API response times and error rates
• Data sync completion status
• Integration performance metrics

Alert Conditions:

• Failed batch processing
• Extended API response times
• High error rates in data sync
• Authentication or permission failures

​

Best Practices for Optimal Performance

​

Data Management

Regular Maintenance:

• Weekly review of integration logs
• Monthly data quality audits
• Quarterly configuration reviews
• Annual authentication credential rotation

Optimization Strategies:

• Monitor API usage patterns
• Optimize sync scheduling for off-peak hours
• Regular cleanup of unused or duplicate data
• Performance tuning based on usage patterns

​

Troubleshooting Preparation

Diagnostic Information:

• Maintain current integration logs
• Document configuration changes
• Keep backup of critical data
• Monitor system performance trends

This understanding of integration nuances will help you successfully implement and maintain the WeGive Planning Center integration while avoiding common pitfalls and ensuring optimal performance for your church management needs.