Recurring Donation Mapping

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: ScheduledDonation
Sync Direction: WeGive → DonorPerfect (Push Only)

Recurring Donation Overview

Integration Approach

Pledge vs. Scheduled Donation

WeGive Side:

ScheduledDonation: Recurring giving setup
Individual Transaction records for each payment
Flexible frequency options (monthly, quarterly, annual)

DonorPerfect Side:

dppledge: Pledge commitment record
dpgift: Individual payment records linked to pledge
Simplified frequency mapping (defaults to monthly)

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

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

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

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

WeGive Scheduled Donation:

Amount: $50.00 (5000 cents)
Processing Fee: $1.75 (175 cents)

DonorPerfect Pledge:

Bill Amount: $51.75 ((5000 + 175) / 100)
Reflects total amount charged to donor

Fee-Covered Recurring Gift

WeGive Scheduled Donation:

Amount: $50.00 (5000 cents)
Processing Fee: $0.00 (donor covers separately)

DonorPerfect Pledge:

Bill Amount: $50.00 ((5000 + 0) / 100)

Schedule and Frequency

Frequency Mapping

WeGive Frequency	DonorPerfect Field	Value	Notes
Any frequency	`@frequency`	’M’	Hardcoded to Monthly

Limitation: DonorPerfect integration currently maps all recurring gifts as monthly frequency, regardless of actual WeGive schedule.

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

WeGive Field	DonorPerfect Field	Value	Notes
Generated	`@gift_narrative`	”Online gift through WeGive”	Standard description

Narrative Examples:

Regular pledge: “Online gift through WeGive”
Anonymous pledge: “Online gift through WeGive (Anonymous)“

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

Transaction Processing:

Each scheduled payment creates a dpgift record
Gift record includes @pledge_payment = 'Y'
Links back to original pledge via donor ID and dates
Payment status tracked in both systems

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

Status Indicators:

Active pledges with regular payments
Paused pledges with temporary holds
Cancelled pledges with stopped payments
Completed pledges with fulfilled commitments

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

Scheduled Donation Setup
Donor sets up recurring gift in WeGive
Donor Validation
Verify donor exists in DonorPerfect (create if needed)
Pledge Record Creation
Create pledge record in DonorPerfect dppledge table
Payment Processing
First payment creates linked dpgift record
Ongoing Sync
Subsequent payments automatically link to pledge

Schedule Modification Handling

Amount Changes

Process:

Update pledge amount in DonorPerfect
Future payments reflect new amount
Historical payments remain unchanged
Status updated to reflect modification

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

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

Required Parameters:

@pledge_id (empty for new pledges)
@donor_id (required)
@gift_date (MM/DD/YYYY format)
@start_date (MM/DD/YYYY format)
@bill (decimal dollars)
@frequency = 'M'
@user_id = 'WeGive'

Optional Parameters

Additional Fields:

@gift_narrative (description)
@gl_code (fund designation)
@pledge_status (active/cancelled)

Query Operations

Pledge Lookup

SQL Query Example:

SELECT pledge_id, donor_id, gift_date, bill, frequency
FROM dppledge
WHERE user_id = 'WeGive'
  AND start_date >= 'MM/DD/YYYY'
ORDER BY pledge_id DESC

Error Handling

Common Pledge Sync Issues

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

Error Scenarios:

Payment processing failures
Expired payment methods
Insufficient funds
Bank declines

Resolution Process:

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

Automatic Sync Events:

New scheduled donation created
Recurring payment processed
Schedule modifications (amount, frequency)
Donation cancellation or pause
Donor profile updates

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

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 Processing Checks:

Valid payment method on file
Sufficient account balance
Active pledge record exists
Proper payment amount calculation

Monitoring and Reporting

Pledge Performance

Dashboard Metrics:

Active pledge count and total value
Payment success rates
Pledge completion rates
Average pledge duration

Financial Reconciliation

Accuracy Verification:

Pledge amount vs. payment totals
Fee inclusion verification
Payment frequency accuracy
Status consistency checks

Limitations and Considerations

Known Limitations

Frequency Mapping

Limitation: All pledges mapped as monthly frequency in DonorPerfect

Impact:

DonorPerfect reports may not reflect actual payment schedule
Actual timing controlled by WeGive system
Payment dates may not align with monthly expectation

Schedule Modifications

Limitation: Limited support for complex schedule changes

Impact:

Frequency changes don’t sync to DonorPerfect
Amount changes require pledge updates
Pause/resume functionality may not reflect perfectly

Best Practices

Plan Pledge Structure
Design recurring giving programs with DonorPerfect limitations in mind
Monitor Payment Success
Regularly review payment processing and pledge status
Handle Modifications Carefully
Test schedule changes to ensure proper sync behavior
Maintain Data Quality
Keep donor and fund information accurate and up-to-date

Troubleshooting

Common Recurring Donation Issues

Pledges Not Creating

Possible Causes:

Recurring donation sync disabled
Donor missing from DonorPerfect
Invalid pledge amount
API authentication issues

Solutions:

Enable recurring donation tracking
Verify donor sync status
Check amount calculation logic
Test API credentials

Payments Not Linking to Pledges

Possible Causes:

Pledge record missing
Donor ID mismatch
Date formatting issues

Solutions:

Verify pledge creation success
Check donor ID consistency
Review date format requirements

Incorrect Pledge Amounts

Possible Causes:

Fee calculation errors
Amount conversion issues
Currency problems

Solutions:

Review fee inclusion logic
Check amount calculation
Verify currency settings

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

For additional help with recurring donation mapping, contact our support team at support@wegive.com.

Recurring Donation Mapping

Recurring Donation Data Mapping

DonorPerfect Table Reference

Recurring Donation Overview

Integration Approach

Core Pledge Fields

Primary Identifiers

Financial Information

Amount and Payment Details

Amount Calculation Examples

Schedule and Frequency

Gift Narrative and Description

Automatic Description Generation

Payment Processing Integration

Individual Payment Tracking

Status Management

Data Flow Process

Pledge Creation Workflow

Schedule Modification Handling

API Operations

DonorPerfect Pledge Creation

Query Operations

Error Handling

Common Pledge Sync Issues

Payment Processing Errors

Sync Configuration

Recurring Donation Settings

Performance Considerations

Data Quality and Validation

Pre-Sync Validation

Monitoring and Reporting

Limitations and Considerations

Known Limitations

Best Practices

Troubleshooting

Common Recurring Donation Issues

Related Documentation