Data Mapping
Recurring Donation Mapping
Detailed field mapping for recurring donations and pledges between WeGive and DonorPerfect systems.
Recurring Donation Data Mapping
This document details how recurring donations and pledges are mapped between WeGive and DonorPerfect, including pledge creation, payment tracking, and schedule management.DonorPerfect Table Reference
Primary Table:dppledge (Pledge Records)WeGive Model:
ScheduledDonationSync Direction: WeGive → DonorPerfect (Push Only)
Recurring Donation Overview
Integration Approach
Pledge vs. Scheduled Donation
Pledge vs. Scheduled Donation
WeGive Side:
ScheduledDonation: Recurring giving setup- Individual
Transactionrecords for each payment - Flexible frequency options (monthly, quarterly, annual)
dppledge: Pledge commitment recorddpgift: Individual payment records linked to pledge- Simplified frequency mapping (defaults to monthly)
Data Flow Pattern
Data Flow Pattern
Process Overview:
- WeGive scheduled donation creates DonorPerfect pledge
- Individual payments create linked gift records
- Pledge status updates based on payment activity
- Schedule modifications sync to pledge record
Core Pledge Fields
Primary Identifiers
Pledge Identification
Pledge Identification
| WeGive Field | DonorPerfect Field | Type | Notes |
|---|---|---|---|
dp_id | @pledge_id | Integer | Auto-generated DonorPerfect pledge ID |
source.dp_id | @donor_id | Integer | Links to donor record |
| N/A | @user_id | String | Always set to ‘WeGive’ |
Relationship Linking
Relationship Linking
Connection Strategy:
- Each WeGive scheduled donation creates one DonorPerfect pledge
- Individual payments reference the pledge ID
- Donor must exist in DonorPerfect before creating pledge
- Pledge ID stored back in WeGive for payment linking
Financial Information
Amount and Payment Details
Amount Calculation: Includes processing fees in pledge amount, matching the total charged to donor.
| WeGive Field | DonorPerfect Field | Calculation | Notes |
|---|---|---|---|
amount + fees | @bill | (amount + fees) / 100 | Total pledge amount in dollars |
created_at | @gift_date | MM/DD/YYYY | Pledge creation date |
created_at | @start_date | MM/DD/YYYY | First payment date |
Amount Calculation Examples
Standard Recurring Gift
Standard Recurring Gift
WeGive Scheduled Donation:
- Amount: $50.00 (5000 cents)
- Processing Fee: $1.75 (175 cents)
- Bill Amount: $51.75 ((5000 + 175) / 100)
- Reflects total amount charged to donor
Fee-Covered Recurring Gift
Fee-Covered Recurring Gift
WeGive Scheduled Donation:
- Amount: $50.00 (5000 cents)
- Processing Fee: $0.00 (donor covers separately)
- Bill Amount: $50.00 ((5000 + 0) / 100)
Schedule and Frequency
Frequency Mapping
Frequency Mapping
| WeGive Frequency | DonorPerfect Field | Value | Notes |
|---|---|---|---|
| Any frequency | @frequency | ’M’ | Hardcoded to Monthly |
Schedule Details
Schedule Details
Date Handling:
- Start Date: Set to scheduled donation creation date
- Gift Date: Also set to creation date
- Actual payment dates handled by individual gift records
- Schedule modifications require pledge updates
Gift Narrative and Description
Automatic Description Generation
Standard Pledge Narrative
Standard Pledge Narrative
| WeGive Field | DonorPerfect Field | Value | Notes |
|---|---|---|---|
| Generated | @gift_narrative | ”Online gift through WeGive” | Standard description |
- Regular pledge: “Online gift through WeGive”
- Anonymous pledge: “Online gift through WeGive (Anonymous)”
Description Consistency
Description Consistency
Matching Records:
- Pledge narrative matches individual payment narratives
- Consistent branding across all related records
- Anonymous handling applies to both pledge and payments
Payment Processing Integration
Individual Payment Tracking
Payment-to-Pledge Linking
Payment-to-Pledge Linking
Transaction Processing:
- Each scheduled payment creates a
dpgiftrecord - Gift record includes
@pledge_payment = 'Y' - Links back to original pledge via donor ID and dates
- Payment status tracked in both systems
Payment Sequence
Payment Sequence
Processing Flow:
- Pledge created in DonorPerfect from scheduled donation
- First payment processes and creates linked gift record
- Subsequent payments automatically link to pledge
- Failed payments update pledge status accordingly
Status Management
Pledge Status Tracking
Pledge Status Tracking
Status Indicators:
- Active pledges with regular payments
- Paused pledges with temporary holds
- Cancelled pledges with stopped payments
- Completed pledges with fulfilled commitments
Automatic Updates
Automatic Updates
Status Synchronization:
- Payment success/failure updates pledge status
- Schedule modifications sync to DonorPerfect
- Cancellations properly close pledge records
- Reactivations update pledge accordingly
Data Flow Process
Pledge Creation Workflow
1
Scheduled Donation Setup
Donor sets up recurring gift in WeGive
2
Donor Validation
Verify donor exists in DonorPerfect (create if needed)
3
Pledge Record Creation
Create pledge record in DonorPerfect dppledge table
4
Payment Processing
First payment creates linked dpgift record
5
Ongoing Sync
Subsequent payments automatically link to pledge
Schedule Modification Handling
Amount Changes
Amount Changes
Process:
- Update pledge amount in DonorPerfect
- Future payments reflect new amount
- Historical payments remain unchanged
- Status updated to reflect modification
Frequency Changes
Frequency Changes
Limitation:
- DonorPerfect frequency remains ‘M’ (Monthly)
- Actual schedule managed by WeGive system
- Payment timing controlled by WeGive processing
- No frequency sync to DonorPerfect
Cancellation Handling
Cancellation Handling
Process:
- Pledge status updated to cancelled
- No new payment records created
- Historical data preserved
- Donor communication handled separately
API Operations
DonorPerfect Pledge Creation
dp_savepledge Action
dp_savepledge Action
Required Parameters:
Optional Parameters
Optional Parameters
Additional Fields:
Query Operations
Pledge Lookup
Pledge Lookup
SQL Query Example:
Error Handling
Common Pledge Sync Issues
Pledge Dependencies: Pledges require valid donor records and fund GL codes before creation.
| Error Type | Cause | Resolution |
|---|---|---|
| Invalid Donor | Donor doesn’t exist in DonorPerfect | Auto-create donor, retry pledge |
| Invalid Amount | Negative or zero pledge amount | Skip creation, log error |
| Date Format | Invalid start/gift date format | Correct format, retry |
| Duplicate Pledge | Pledge already exists for donor | Update existing pledge |
| API Timeout | DonorPerfect API unavailable | Retry with backoff delay |
Payment Processing Errors
Failed Payment Handling
Failed Payment Handling
Error Scenarios:
- Payment processing failures
- Expired payment methods
- Insufficient funds
- Bank declines
- Retry payment according to schedule
- Update pledge status if multiple failures
- Notify donor of payment issues
- Maintain pledge record for future attempts
Sync Configuration
Recurring Donation Settings
Sync Triggers
Sync Triggers
Automatic Sync Events:
- New scheduled donation created
- Recurring payment processed
- Schedule modifications (amount, frequency)
- Donation cancellation or pause
- Donor profile updates
Sync Timing
Sync Timing
Processing Schedule:
- Real-time: New pledges sync immediately
- Payment Processing: Individual payments sync as processed
- Status Updates: Schedule changes sync within minutes
- Error Recovery: Failed syncs retry automatically
Performance Considerations
Pledge Management
- Efficient pledge creation and updates
- Batch processing for multiple changes
- Automatic status synchronization
- Optimized query performance
Payment Integration
- Real-time payment-to-pledge linking
- Automatic gift record creation
- Status updates for payment outcomes
- Comprehensive error handling
Data Quality and Validation
Pre-Sync Validation
Pledge Requirements
Pledge Requirements
Validation Rules:
- Donor must exist in DonorPerfect
- Pledge amount must be positive
- Start date must be valid
- Frequency must be supported
- Fund designation must be valid
Payment Validation
Payment Validation
Payment Processing Checks:
- Valid payment method on file
- Sufficient account balance
- Active pledge record exists
- Proper payment amount calculation
Monitoring and Reporting
Pledge Performance
Pledge Performance
Dashboard Metrics:
- Active pledge count and total value
- Payment success rates
- Pledge completion rates
- Average pledge duration
Financial Reconciliation
Financial Reconciliation
Accuracy Verification:
- Pledge amount vs. payment totals
- Fee inclusion verification
- Payment frequency accuracy
- Status consistency checks
Limitations and Considerations
Known Limitations
Important Limitations:
Frequency Mapping
Frequency Mapping
Limitation: All pledges mapped as monthly frequency in DonorPerfectImpact:
- DonorPerfect reports may not reflect actual payment schedule
- Actual timing controlled by WeGive system
- Payment dates may not align with monthly expectation
Schedule Modifications
Schedule Modifications
Limitation: Limited support for complex schedule changesImpact:
- Frequency changes don’t sync to DonorPerfect
- Amount changes require pledge updates
- Pause/resume functionality may not reflect perfectly
Best Practices
1
Plan Pledge Structure
Design recurring giving programs with DonorPerfect limitations in mind
2
Monitor Payment Success
Regularly review payment processing and pledge status
3
Handle Modifications Carefully
Test schedule changes to ensure proper sync behavior
4
Maintain Data Quality
Keep donor and fund information accurate and up-to-date
Troubleshooting
Common Recurring Donation Issues
Pledges Not Creating
Pledges Not Creating
Possible Causes:
- Recurring donation sync disabled
- Donor missing from DonorPerfect
- Invalid pledge amount
- API authentication issues
- Enable recurring donation tracking
- Verify donor sync status
- Check amount calculation logic
- Test API credentials
Payments Not Linking to Pledges
Payments Not Linking to Pledges
Possible Causes:
- Pledge record missing
- Donor ID mismatch
- Date formatting issues
- Verify pledge creation success
- Check donor ID consistency
- Review date format requirements
Incorrect Pledge Amounts
Incorrect Pledge Amounts
Possible Causes:
- Fee calculation errors
- Amount conversion issues
- Currency problems
- Review fee inclusion logic
- Check amount calculation
- Verify currency settings
Related Documentation
Transaction Mapping
How individual payments link to pledges
Donor Mapping
Donor record requirements for pledges
Fund Management
GL code setup for recurring gifts
Configuration Guide
Configure recurring donation sync settings