​

Gift Mapping

This document provides comprehensive mapping details between WeGive transaction objects and Virtuous gift records, including batch processing capabilities and integration with both V1 and V2 contact structures.

​

Overview

Virtuous uses the Gift object to represent all financial interactions including donations, pledge payments, and recurring gifts. WeGive maps these to the Transaction object with appropriate categorization and metadata, with enhanced processing capabilities for both individual and batch operations.

​

Core Gift Mapping

​

Primary Fields

WeGive Field	Virtuous Field	Type	Required	Transformation
id	Correlation ID	String	No	Stored in WeGive virtuous_id
amount	Amount	Decimal	Yes	Cents to dollars (÷100)
created_at	GiftDate	DateTime	Yes	Date formatting
owner (donor_id)	ContactId	Integer	Yes	Contact reference mapping
status	GiftStatus	String	No	Status enumeration
source_type	GiftType	String	No	Payment method mapping
fee_amount	Fee	Decimal	No	Processing fees (cents to dollars)

​

Extended Fields

WeGive Field	Virtuous Field	Transformation	Notes
currency	CurrencyCode	Direct mapping	Defaults to USD
reference	Reference	Reference tracking	Transaction ID or check number
memo	Note	Direct mapping	Internal notes or memo
fund_id	ProjectId	Project correlation	Primary project designation

​

Gift Types and Categories

​

Standard Gift Processing

Donation Gift Mapping:

• Amount: Converted from cents to dollars with proper decimal formatting
• Date: Transaction date converted to Virtuous date format
• Contact Reference: Linked to appropriate Virtuous contact based on integration version
• Project: Mapped to corresponding Virtuous project for fund designation
• Payment Method: Converted to appropriate Virtuous gift type

​

Recurring Gift Transactions

Recurring Gift Processing:

• Schedule Reference: Links to RecurringGift object in Virtuous
• Sequence Tracking: Maintains order in recurring gift series
• Amount Consistency: Ensures amount matches recurring gift schedule
• Project Alignment: Uses project from recurring gift configuration

​

Pledge Payment Processing

Pledge Payment Handling:

• Pledge Reference: Links to existing pledge commitment
• Payment Sequence: Tracks payment number in pledge series
• Balance Tracking: Updates pledge balance automatically
• Project Designation: Inherits project from pledge setup

​

Payment Method Mapping

​

Source Type Transformation

WeGive Source Type	Virtuous Gift Type	Description
card	CreditCard	Credit/debit card payments
bank	ACH	Electronic fund transfers
check	Check	Check payments
cash	Cash	Cash donations
venmo	DigitalWallet	Venmo payments
paypal	DigitalWallet	PayPal payments
crypto	Cryptocurrency	Cryptocurrency donations
stock	Stock	Stock/securities donations
wire	WireTransfer	Wire transfer payments
other	Other	Unknown or other methods

​

Payment Method Processing

Payment Type Rules:

• Default to most appropriate Virtuous gift type
• Maintain payment method for reporting purposes
• Handle special payment types (crypto, stock) appropriately
• Support custom payment method mapping

​

Project Designation Mapping

​

Single Project Designation

Simple Project Assignment:

• WeGive fund maps directly to Virtuous project
• Project ID correlation maintained through integration
• Default project used when no specific designation provided
• Project validation ensures active status

​

Multiple Project Allocations

Split Gift Handling:

• WeGive fund allocations map to multiple Virtuous designations
• Allocation amounts distributed across projects
• Percentage-based or amount-based splits supported
• Total validation ensures gift amount accuracy

​

Default Project Management

No Project Specified:

• Uses configured default project ID from integration settings
• Ensures all gifts have proper project designation
• Prevents gift creation failures due to missing projects
• Supports organizational default fund strategies

​

Contact Reference Mapping

​

V1 Contact Reference

Direct Contact Mapping:

• WeGive donor ID maps to Virtuous contact ID
• Simple one-to-one relationship
• Contact validation ensures donor exists in Virtuous
• Direct contact ID correlation

​

V2 Enhanced Contact Reference

Hierarchical Contact Mapping:

• WeGive donor maps to ContactIndividual within Contact
• Contact hierarchy maintained for gift attribution
• Primary individual designation for household gifts
• Organization contact handling for corporate gifts

​

V2 Contact Resolution

Individual Gifts:

• Attribute to specific ContactIndividual
• Maintain household relationship context
• Primary individual designation when appropriate
• Personal vs. household gift distinction

Household Gifts:

• Attribute to household Contact when appropriate
• Coordinate with primary individual
• Shared gift recognition and acknowledgment
• Family giving pattern tracking

​

Data Transformation

​

Amount Processing

Currency Conversion:

• Convert from cents to dollars with 2 decimal precision
• Handle international currency when applicable
• Maintain precision for accounting accuracy
• Support currency-specific formatting

​

Date Processing

Date Handling:

• Convert UTC timestamps to Virtuous date format
• Respect organization timezone settings
• Handle date-only vs. datetime fields appropriately
• Maintain chronological accuracy

​

Status Mapping

Transaction Status Processing:

• Success → Completed gift status
• Refunded → Reversed or refunded gift status
• Failed → Not synced to Virtuous
• Pending → Held for manual review

​

Sync Operations

​

Individual Gift Processing

​

Push Operation (WeGive → Virtuous)

Create New Gift:

• Validate all required fields are present
• Ensure contact exists in Virtuous (create if needed)
• Map payment method to appropriate gift type
• Assign to correct project designation
• Create gift with complete information
• Store correlation ID for future updates

Update Existing Gift:

• Use correlation ID for gift identification
• Update amount, date, or project if changed
• Handle status changes (refunds, corrections)
• Maintain gift history and audit trail

​

Pull Operation (Virtuous → WeGive)

Import Gift:

• Map Virtuous gift fields to WeGive transaction structure
• Resolve contact reference to WeGive donor
• Convert amount and date to WeGive format
• Create or update WeGive transaction record
• Store correlation ID for bidirectional sync

​

Batch Processing

​

Enhanced Batch Operations

Batch Gift Creation:

• Process multiple gifts in single API call
• Optimize API usage for large transaction volumes
• Maintain transaction order and relationships
• Handle batch-level error reporting

Batch Processing Benefits:

• Improved performance for large data sets
• Reduced API call volume
• Enhanced error handling and reporting
• Coordinated gift creation for events

​

Daily Batch Jobs

Scheduled Processing:

• Daily batch jobs for bulk transaction sync
• Off-peak processing to minimize impact
• Comprehensive error handling and retry logic
• Performance monitoring and optimization

​

Validation and Error Handling

​

Data Validation

Required Field Validation:

• Amount must be positive value
• Gift date is required and valid
• Contact reference must exist
• Project reference must be valid and active

Business Rule Validation:

• Gift amount reasonable for donor profile
• Date within acceptable range
• Payment method appropriate for amount
• Project designation allowed for gift type

​

Error Handling

Common Gift Errors:

• Invalid contact reference
• Missing or inactive project
• Amount format errors
• Date validation failures

Error Recovery:

• Automatic retry for transient failures
• Contact creation for missing donors
• Default project assignment when needed
• Manual review queue for complex issues

​

Performance Optimization

​

Individual vs. Batch Processing

Individual Gift Processing:

• Real-time processing for immediate sync
• Individual error handling and resolution
• Immediate feedback for gift processing
• Lower throughput but immediate results

Batch Processing Advantages:

• Higher throughput for large volumes
• Efficient API usage
• Coordinated error handling
• Optimized for daily processing workflows

​

Processing Strategies

Real-time Processing:

• High-priority gifts processed immediately
• Major gift notifications
• Event-based gift processing
• Immediate donor acknowledgment needs

Batch Processing:

• Regular donations processed in daily batches
• Historical data imports
• Bulk gift corrections
• Periodic reconciliation

​

Gift Recognition and Acknowledgment

​

Acknowledgment Coordination

Gift Recognition:

• Coordinate acknowledgment between systems
• Maintain donor communication preferences
• Support custom acknowledgment workflows
• Track acknowledgment status

Tax Receipt Management:

• Support tax-deductible gift tracking
• Coordinate receipt generation
• Maintain gift tax status
• Support receipt resend capabilities

​

Integration with Recurring Gifts

​

Recurring Gift Relationship

Recurring Gift Tracking:

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

​

Schedule Management

Recurring Gift Coordination:

• Schedule changes reflected in individual gifts
• Amount modifications tracked appropriately
• Payment method updates coordinated
• Project changes applied to future gifts

​

Special Gift Types

​

In-Kind Gifts

Non-Cash Gift Handling:

• Special processing for in-kind donations
• Value assessment and tracking
• Appropriate tax treatment
• Description and documentation

​

Planned Gifts

Planned Gift Processing:

• Estate gift tracking and processing
• Beneficiary designation management
• Value realization timing
• Special recognition requirements

​

Corporate Gifts

Organization Gift Handling:

• Corporate contact attribution
• Employee matching gift coordination
• Corporate foundation gift tracking
• Business relationship maintenance

This comprehensive gift mapping ensures accurate financial transaction synchronization between WeGive and Virtuous while supporting various gift types, processing methods, and integration versions for optimal donation management.