> ## Documentation Index
> Fetch the complete documentation index at: https://wegive.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Neon Donation Mapping

> Detailed mapping between Neon CRM donation objects and WeGive transaction records

# 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "campaign": {
    "id": "789",
    "name": "Annual Fundraiser 2024",
    "status": "ACTIVE"
  }
}
```

## Complete Donation Structure

### Full Neon Donation Object

```json theme={null}
{
  "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

```javascript theme={null}
// 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:

```json theme={null}
{
  "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

```http theme={null}
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

```http theme={null}
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

```http theme={null}
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.