Skip to main content

​
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

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)
Process Overview:
  1. WeGive scheduled donation creates DonorPerfect pledge
  2. Individual payments create linked gift records
  3. Pledge status updates based on payment activity
  4. Schedule modifications sync to pledge record

​
Core Pledge Fields

​
Primary Identifiers

WeGive FieldDonorPerfect FieldTypeNotes
dp_id@pledge_idIntegerAuto-generated DonorPerfect pledge ID
source.dp_id@donor_idIntegerLinks to donor record
N/A@user_idStringAlways set to ‘WeGive’
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 FieldDonorPerfect FieldCalculationNotes
amount + fees@bill(amount + fees) / 100Total pledge amount in dollars
created_at@gift_dateMM/DD/YYYYPledge creation date
created_at@start_dateMM/DD/YYYYFirst payment date

​
Amount Calculation Examples

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
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

WeGive FrequencyDonorPerfect FieldValueNotes
Any frequency@frequency’M’Hardcoded to Monthly
Limitation: DonorPerfect integration currently maps all recurring gifts as monthly frequency, regardless of actual WeGive schedule.
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

WeGive FieldDonorPerfect FieldValueNotes
Generated@gift_narrative”Online gift through WeGive”Standard description
Narrative Examples:
  • Regular pledge: “Online gift through WeGive”
  • Anonymous pledge: “Online gift through WeGive (Anonymous)”
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

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
Processing Flow:
  1. Pledge created in DonorPerfect from scheduled donation
  2. First payment processes and creates linked gift record
  3. Subsequent payments automatically link to pledge
  4. Failed payments update pledge status accordingly

​
Status Management

Status Indicators:
  • Active pledges with regular payments
  • Paused pledges with temporary holds
  • Cancelled pledges with stopped payments
  • Completed pledges with fulfilled commitments
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

Process:
  • Update pledge amount in DonorPerfect
  • Future payments reflect new amount
  • Historical payments remain unchanged
  • Status updated to reflect modification
Limitation:
  • DonorPerfect frequency remains ‘M’ (Monthly)
  • Actual schedule managed by WeGive system
  • Payment timing controlled by WeGive processing
  • No frequency sync to DonorPerfect
Process:
  • Pledge status updated to cancelled
  • No new payment records created
  • Historical data preserved
  • Donor communication handled separately

​
API Operations

​
DonorPerfect Pledge Creation

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'
Additional Fields:
@gift_narrative (description)
@gl_code (fund designation)
@pledge_status (active/cancelled)

​
Query Operations

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

Pledge Dependencies: Pledges require valid donor records and fund GL codes before creation.
Error TypeCauseResolution
Invalid DonorDonor doesn’t exist in DonorPerfectAuto-create donor, retry pledge
Invalid AmountNegative or zero pledge amountSkip creation, log error
Date FormatInvalid start/gift date formatCorrect format, retry
Duplicate PledgePledge already exists for donorUpdate existing pledge
API TimeoutDonorPerfect API unavailableRetry with backoff delay

​
Payment Processing Errors

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

Automatic Sync Events:
  • New scheduled donation created
  • Recurring payment processed
  • Schedule modifications (amount, frequency)
  • Donation cancellation or pause
  • Donor profile updates
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

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 Processing Checks:
  • Valid payment method on file
  • Sufficient account balance
  • Active pledge record exists
  • Proper payment amount calculation

​
Monitoring and Reporting

Dashboard Metrics:
  • Active pledge count and total value
  • Payment success rates
  • Pledge completion rates
  • Average pledge duration
Accuracy Verification:
  • Pledge amount vs. payment totals
  • Fee inclusion verification
  • Payment frequency accuracy
  • Status consistency checks

​
Limitations and Considerations

​
Known Limitations

Important Limitations:
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
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

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
Possible Causes:
  • Pledge record missing
  • Donor ID mismatch
  • Date formatting issues
Solutions:
  • Verify pledge creation success
  • Check donor ID consistency
  • Review date format requirements
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 [email protected].