Neon Donation Mapping

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

WeGive Field	Neon Field	Data Type	Direction	Required	Transformation
`id`	Correlation ID	UUID/String	-	No	Stored for tracking
`amount`	`amount`	Decimal	Bidirectional	Yes	Cents to dollars (÷100)
`fee_amount`	`donorCoveredFee`	Decimal	Bidirectional	No	Cents to dollars (÷100)
`cover_fees`	Fee calculation	Boolean	Export	No	Used to calculate `donorCoveredFee`
`currency`	Currency	String	Export	No	Default USD

Timing Information

WeGive Field	Neon Field	Data Type	Direction	Required	Transformation
`created_at`	`date`	DateTime	Bidirectional	Yes	ISO 8601 format
`payout.paid_at`	`receivedDate`	Date	Export Only	No	Date formatting

Attribution

WeGive Field	Neon Field	Data Type	Direction	Required	Transformation
`owner` (donor)	`accountId`	Integer	Bidirectional	Yes	Donor correlation
`donor_name`	`donorName`	String	Bidirectional	Yes	Computed from donor
`campaign`	`campaign.id`	Integer	Bidirectional	No	Campaign reference
`anonymous`	`anonymousType`	String	Bidirectional	No	Boolean to string

Tribute Information

WeGive Field	Neon Field	Data Type	Direction	Required	Transformation
`tribute_name`	`tribute.name`	String	Bidirectional	No	Direct mapping
`tribute_type`	`tribute.type`	String	Export	No	Default “Honor”

Integration Fields

WeGive Field	Neon Field	Data Type	Direction	Required	Transformation
`neon_id`	`id`	Integer	Correlation	No	Donation reference
`neon_payment_id`	`payments[0].id`	Integer	Correlation	No	Payment reference

Payment Processing

Payment Method Mapping

Tender Type Mapping

WeGive Source Type	Neon Tender Type	Neon Code	Description
`card`	Credit Card Offline	2	Credit/debit card payments
`bank`	Check	3	ACH and bank transfers
`donor`	Check	3	Donor-funded payments
`cash`	Cash	1	Cash donations
`check`	Check	3	Physical check payments
`other`	Other	10	Other payment methods

Credit Card Processing

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

WeGive Field	Neon Field	Data Type	Transformation
`source.last_four`	`creditCardOffline.cardNumberLastFour`	String	Padded to 4 digits
`source.issuer`	`creditCardOffline.cardTypeCode`	String	Card type mapping
`source.expiration`	`creditCardOffline.expirationMonth/Year`	String	Split MM/YY format
`owner.email_1`	`creditCardOffline.cardHolderEmail`	Email	Cardholder email
`owner.name`	`creditCardOffline.cardHolderName`	String	Cardholder name

Card Type Mapping

WeGive Card Type	Neon Card Code	Full Name
`visa`	V	Visa
`mastercard`	M	MasterCard
`amex`	A	American Express
`discover`	D	Discover

Bank Transfer Processing

For bank transfers (source_type = 'bank'):

WeGive Field	Neon Field	Data Type	Transformation
`source.last_four`	`check.accountNumber`	String	Account number (last 4)
`source.name`	`check.institution`	String	Bank/institution name
`owner.name`	`check.accountOwner`	String	Account owner name
`check.accountType`	Fixed	String	Set to “Checking”

Payment Object Structure

Credit Card Payment

{
  "payments": [
    {
      "amount": 100.00,
      "tenderType": 2,
      "creditCardOffline": {
        "cardHolderName": "John Smith",
        "cardHolderEmail": "john.smith@example.com",
        "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:

WeGive Field	Neon Field	Data Type	Required	Transformation
`campaign.id`	`campaign.id`	Integer	No	Campaign correlation
`campaign.name`	`campaign.name`	String	No	Campaign name
`campaign.status`	`campaign.status`	String	No	Default “ACTIVE”

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": "john.smith@example.com",
        "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

WeGive Anonymous	Neon Anonymous Type	Description
`true`	”ANONYMOUS”	Fully anonymous donation
`false`	”NOT_ANONYMOUS”	Named donation
`null`	”NOT_ANONYMOUS”	Default to named

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:

Integration Path	WeGive Path	Purpose	Level
`donorName`	`donor_name`	Donor name display	Bidirectional
`amount`	`amount`	Donation amount	Bidirectional
`date`	`created_at`	Transaction date	Bidirectional
`receivedDate`	`payout.paid_at`	Payout date	Export only
`anonymousType`	`anonymous`	Anonymous flag	Bidirectional
`donorCoveredFee`	`fee_amount`	Fee amount	Bidirectional
`tribute.name`	`tribute_name`	Tribute name	Bidirectional

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

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

Donation Updates

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

Import from Neon CRM

Donation Search: Uses search API with date filters
Account Matching: Matches Neon accounts to WeGive donors
Transaction Creation: Creates new WeGive transactions
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.