​

Donation Object Mapping

This document details the comprehensive mapping between Neon CRM donation objects and WeGive transaction records, including payment processing, field mappings, and synchronization behavior.

​

Object Overview

​

Neon Donation Object

Represents financial transactions in Neon CRM including gifts, payments, and related processing information.

​

WeGive Transaction Object

Represents donation transactions in WeGive including payment methods, fees, and donor attribution.

​

Core Donation Mapping

​

WeGive Transaction to Neon Donation

​

Financial Information

​

Timing Information

​

Attribution

​

Tribute Information

​

Integration Fields

​

Payment Processing

​

Payment Method Mapping

​

Tender Type Mapping

​

Credit Card Processing

For credit card payments (source_type = 'card'):

​

Card Type Mapping

​

Bank Transfer Processing

For bank transfers (source_type = 'bank'):

​

Payment Object Structure

​

Credit Card Payment

{
  "payments": [
    {
      "amount": 100.00,
      "tenderType": 2,
      "creditCardOffline": {
        "cardHolderName": "John Smith",
        "cardHolderEmail": "[email protected]",
        "cardNumberLastFour": "1234",
        "cardTypeCode": "V",
        "expirationMonth": "12",
        "expirationYear": "25"
      },
      "note": "https://dashboard.wegive.com/payments/donations/12345"
    }
  ]
}

​

Bank Transfer Payment

{
  "payments": [
    {
      "amount": 250.00,
      "tenderType": 3,
      "check": {
        "accountType": "Checking",
        "accountNumber": "5678",
        "institution": "First National Bank",
        "accountOwner": "Jane Doe"
      },
      "note": "https://dashboard.wegive.com/payments/donations/12346"
    }
  ]
}

​

Campaign Integration

​

Campaign Reference

When transactions are associated with campaigns:

​

Campaign Object Structure

{
  "campaign": {
    "id": "789",
    "name": "Annual Fundraiser 2024",
    "status": "ACTIVE"
  }
}

​

Complete Donation Structure

​

Full Neon Donation Object

{
  "id": "12345",
  "accountId": "67890",
  "donorName": "John Smith",
  "amount": 100.00,
  "date": "2024-01-15T10:30:00Z",
  "campaign": {
    "id": "789",
    "name": "Annual Fundraiser 2024",
    "status": "ACTIVE"
  },
  "tribute": {
    "name": "In memory of Sarah Johnson",
    "type": "Honor"
  },
  "anonymousType": "NOT_ANONYMOUS",
  "donorCoveredFee": 3.50,
  "sendAcknowledgeEmail": false,
  "payments": [
    {
      "amount": 100.00,
      "tenderType": 2,
      "creditCardOffline": {
        "cardHolderName": "John Smith",
        "cardHolderEmail": "[email protected]",
        "cardNumberLastFour": "1234",
        "cardTypeCode": "V",
        "expirationMonth": "12",
        "expirationYear": "25"
      },
      "note": "https://dashboard.wegive.com/payments/donations/12345"
    }
  ]
}

​

Data Transformations

​

Amount Conversion

• WeGive Storage: Amounts stored in cents (integer)
• Neon Format: Amounts in dollars (decimal)
• Conversion: WeGive amount ÷ 100 = Neon amount
• Example: WeGive 10000 cents = Neon $100.00

​

Date Formatting

• WeGive Format: ISO 8601 datetime
• Neon Format: ISO 8601 date or datetime
• Timezone: UTC conversion applied
• Example: “2024-01-15T10:30:00Z”

​

Anonymous Type Mapping

​

Fee Calculation

// Donor-covered fee calculation
if (transaction.cover_fees && transaction.fee_amount) {
  donorCoveredFee = transaction.fee_amount / 100;
} else {
  donorCoveredFee = 0;
}

​

Custom Field Mapping

​

Default Donation Mappings

The integration includes pre-configured mappings:

​

Adding Custom Mappings

Organizations can add custom donation field mappings:

{
  "integration": "DONATION",
  "integration_path": "customField.value",
  "wegive_path": "custom_field_name",
  "crm": "NEON",
  "level": "bidirectional"
}

​

Synchronization Behavior

​

Donation Creation

1. Account Verification: Ensures donor account exists in Neon CRM
2. Campaign Sync: Syncs associated campaign if not already present
3. Payment Processing: Creates payment record with donation
4. Correlation Tracking: Stores Neon donation and payment IDs

​

Donation Updates

1. Existing Check: Uses neon_id to identify existing donations
2. Payment Handling: Updates existing payments or creates new ones
3. Field Updates: Updates modifiable fields only
4. Immutable Fields: Respects Neon CRM restrictions on changes

​

Import from Neon CRM

1. Donation Search: Uses search API with date filters
2. Account Matching: Matches Neon accounts to WeGive donors
3. Transaction Creation: Creates new WeGive transactions
4. Status Setting: Sets appropriate transaction status

​

Error Handling

​

Validation Errors

• Missing Account: Clear errors when donor account not found
• Invalid Amount: Amount validation with minimum/maximum checks
• Payment Method: Validation of payment method data
• Date Format: Date validation and format correction

​

Resolution Strategies

• Account Creation: Automatic donor account creation when missing
• Data Correction: Tools for correcting invalid payment data
• Retry Logic: Automatic retry for transient failures
• Manual Review: Administrative interface for complex errors

​

Performance Considerations

​

Batch Processing

• Large Imports: Efficient processing of large donation datasets
• Payment Optimization: Optimized payment creation and updates
• Campaign Batching: Batch campaign synchronization before donations
• Error Handling: Graceful handling of partial batch failures

​

API Optimization

• Rate Limiting: Respectful API usage with throttling
• Parallel Processing: Concurrent processing where possible
• Memory Management: Efficient memory usage for large datasets
• Caching: Smart caching of frequently accessed data

​

API Examples

​

Creating Donation

POST /v2/donations
{
  "accountId": "67890",
  "donorName": "Jane Doe", 
  "amount": 250.00,
  "date": "2024-01-20T14:30:00Z",
  "campaign": {
    "id": "789",
    "name": "Annual Fundraiser 2024",
    "status": "ACTIVE"
  },
  "anonymousType": "NOT_ANONYMOUS",
  "donorCoveredFee": 7.50,
  "sendAcknowledgeEmail": false,
  "payments": [
    {
      "amount": 250.00,
      "tenderType": 3,
      "check": {
        "accountType": "Checking",
        "accountNumber": "9876",
        "institution": "Community Bank",
        "accountOwner": "Jane Doe"
      },
      "note": "https://dashboard.wegive.com/payments/donations/12347"
    }
  ]
}

​

Searching Donations

POST /v2/donations/search
{
  "searchFields": [
    {
      "field": "Donation Created Date",
      "operator": "GREATER_THAN",
      "value": "2024-01-01"
    },
    {
      "field": "Email",
      "operator": "NOT_BLANK"
    }
  ],
  "outputFields": [
    "Donation Amount",
    "Account ID",
    "Donation ID",
    "Payment ID",
    "Donation Created Date"
  ],
  "pagination": {
    "currentPage": 0,
    "pageSize": 200
  }
}

​

Updating Donation

PUT /v2/donations/12345
{
  "donorCoveredFee": 5.00,
  "tribute": {
    "name": "Updated tribute name",
    "type": "Honor"
  }
}

​

Best Practices

​

Data Quality

• Amount Validation: Ensure amounts are positive and realistic
• Payment Verification: Verify payment method details before sync
• Date Consistency: Maintain consistent date formats and timezones
• Campaign Validation: Ensure campaigns exist before donation creation

​

Integration Management

• Regular Monitoring: Monitor donation sync performance and errors
• Fee Tracking: Track and validate fee calculations
• Payment Security: Ensure secure handling of payment information
• Reconciliation: Regular reconciliation between platforms

​

Performance Optimization

• Batch Operations: Use batch operations for large donation imports
• Incremental Sync: Sync only new or modified donations
• Error Recovery: Implement robust error recovery mechanisms
• Monitoring: Monitor API usage and performance metrics

This comprehensive donation mapping ensures accurate financial transaction synchronization between WeGive and Neon CRM while maintaining payment security and data integrity.