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

# Transaction Data Mapping

> Detailed field mapping for transactions and gifts between WeGive and DonorPerfect systems.

# Transaction Data Mapping

This document details how donation transactions are mapped between WeGive and DonorPerfect, including one-time gifts, recurring donations, and tribute gifts.

## DonorPerfect Table Reference

**Primary Table**: `dpgift` (Gift Records)\
**WeGive Model**: `Transaction`\
**Sync Direction**: WeGive → DonorPerfect (Push Only)

## Core Transaction Fields

### Primary Identifiers

<AccordionGroup>
  <Accordion title="Gift Identification">
    | WeGive Field  | DonorPerfect Field | Type    | Notes                               |
    | ------------- | ------------------ | ------- | ----------------------------------- |
    | `dp_id`       | `@gift_id`         | Integer | Auto-generated DonorPerfect gift ID |
    | `owner.dp_id` | `@donor_id`        | Integer | Links to donor record               |
    | N/A           | `@record_type`     | String  | Always set to 'G' (Gift)            |
    | N/A           | `@user_id`         | String  | Always set to 'WeGive'              |
  </Accordion>

  <Accordion title="Transaction Linking">
    **Relationship Mapping**:

    * Each WeGive transaction creates one DonorPerfect gift record
    * Donor must exist in DonorPerfect before transaction sync
    * Automatic donor creation if donor doesn't exist
    * Gift ID stored back in WeGive for future reference
  </Accordion>
</AccordionGroup>

## Financial Information

### Amount Processing

<Warning>
  **Critical**: WeGive stores amounts in cents (integer), DonorPerfect uses dollars (decimal). Automatic conversion and fee handling applied.
</Warning>

| WeGive Field           | DonorPerfect Field  | Calculation            | Notes                          |
| ---------------------- | ------------------- | ---------------------- | ------------------------------ |
| `amount`               | `@amount`           | `(amount - fee) / 100` | Net donation amount in dollars |
| `fee`                  | Not directly mapped | Used in calculation    | Processing fee deducted        |
| `destination.currency` | `@currency`         | Direct mapping         | Currency code (e.g., 'USD')    |

#### Amount Calculation Examples

<AccordionGroup>
  <Accordion title="Standard Donation">
    **WeGive Transaction**:

    * Amount: \$100.00 (10000 cents)
    * Fee: \$2.90 (290 cents)

    **DonorPerfect Gift**:

    * Amount: \$97.10 ((10000 - 290) / 100)
  </Accordion>

  <Accordion title="Fee-Covered Donation">
    **WeGive Transaction**:

    * Amount: \$100.00 (10000 cents)
    * Fee: \$0.00 (0 cents, donor covered fee)

    **DonorPerfect Gift**:

    * Amount: \$100.00 ((10000 - 0) / 100)
  </Accordion>
</AccordionGroup>

### Date and Timing

| WeGive Field | DonorPerfect Field | Format     | Notes                       |
| ------------ | ------------------ | ---------- | --------------------------- |
| `created_at` | `@gift_date`       | MM/DD/YYYY | Transaction processing date |

<Note>
  **Date Format**: DonorPerfect requires MM/DD/YYYY format. Other formats will cause sync failures.
</Note>

## Fund and Campaign Attribution

### Fund Designation

<AccordionGroup>
  <Accordion title="Fund Mapping">
    | WeGive Field      | DonorPerfect Field  | Type   | Notes                         |
    | ----------------- | ------------------- | ------ | ----------------------------- |
    | `fund.dp_gl_code` | `@gl_code`          | String | DonorPerfect GL code for fund |
    | `fund.name`       | Not directly mapped | String | Description in GL code table  |
  </Accordion>

  <Accordion title="GL Code Requirements">
    **Fund Setup Requirements**:

    * WeGive funds must have associated DonorPerfect GL codes
    * GL codes must exist in DonorPerfect before transaction sync
    * Automatic GL code creation for new WeGive funds
    * Fund names sync to GL code descriptions
  </Accordion>
</AccordionGroup>

## Gift Types and Classifications

### Recurring Donation Handling

<AccordionGroup>
  <Accordion title="Scheduled Donations">
    | WeGive Field            | DonorPerfect Field | Value      | Notes                         |
    | ----------------------- | ------------------ | ---------- | ----------------------------- |
    | `scheduled_donation_id` | `@pledge_payment`  | 'Y' or 'N' | 'Y' if part of recurring gift |

    **Logic**:

    * Regular donations: `@pledge_payment = 'N'`
    * Recurring donations: `@pledge_payment = 'Y'`
    * Links to pledge record in DonorPerfect
  </Accordion>

  <Accordion title="Recurring Gift Integration">
    **Process Flow**:

    1. Scheduled donation creates pledge in DonorPerfect
    2. Individual payments reference pledge record
    3. Payment status tracked in both systems
    4. Pledge modifications sync automatically
  </Accordion>
</AccordionGroup>

### Tribute and Memorial Gifts

<AccordionGroup>
  <Accordion title="Tribute Information">
    | WeGive Field   | DonorPerfect Field | Type   | Max Length | Notes                                |
    | -------------- | ------------------ | ------ | ---------- | ------------------------------------ |
    | `tribute_name` | `@memory_honor`    | String | 50         | In honor/memory of name              |
    | `tribute_type` | Not mapped         | String | -          | Honor vs. memorial not distinguished |
  </Accordion>

  <Accordion title="Tribute Processing">
    **Mapping Rules**:

    * Only tribute name syncs to DonorPerfect
    * Tribute type (honor vs. memorial) not distinguished
    * Empty tribute fields sync as null
    * Tribute notifications handled separately
  </Accordion>
</AccordionGroup>

## Gift Narrative and Notes

### Automatic Gift Description

<AccordionGroup>
  <Accordion title="Standard Gift Narrative">
    | WeGive Field | DonorPerfect Field | Value                        | Notes                   |
    | ------------ | ------------------ | ---------------------------- | ----------------------- |
    | Generated    | `@gift_narrative`  | "Online gift through WeGive" | Standard description    |
    | `anonymous`  | `@gift_narrative`  | "+ (Anonymous)"              | Added if anonymous gift |
  </Accordion>

  <Accordion title="Gift Narrative Examples">
    **Regular Gift**:

    ```
    "Online gift through WeGive"
    ```

    **Anonymous Gift**:

    ```
    "Online gift through WeGive (Anonymous)"
    ```

    **Tribute Gift**:

    ```
    "Online gift through WeGive - In honor of [Name]"
    ```
  </Accordion>
</AccordionGroup>

## Data Flow Process

### Transaction Sync Workflow

<Steps>
  <Step title="Transaction Created">
    New donation processed in WeGive system
  </Step>

  <Step title="Donor Validation">
    Verify donor exists in DonorPerfect (create if needed)
  </Step>

  <Step title="Amount Calculation">
    Calculate net amount after fee deduction
  </Step>

  <Step title="Gift Record Creation">
    Create gift record in DonorPerfect dpgift table
  </Step>

  <Step title="ID Assignment">
    Store DonorPerfect gift ID back in WeGive
  </Step>
</Steps>

### Error Handling

<Warning>
  **Transaction Sync Errors**: Failed transactions are automatically retried with exponential backoff.
</Warning>

| Error Type            | Cause                               | Resolution                           |
| --------------------- | ----------------------------------- | ------------------------------------ |
| **Invalid Donor**     | Donor doesn't exist in DonorPerfect | Auto-create donor, retry transaction |
| **Invalid GL Code**   | Fund GL code not found              | Create GL code, retry transaction    |
| **Amount Validation** | Negative or zero amount             | Skip transaction, log error          |
| **Date Format**       | Invalid date format                 | Correct format, retry                |
| **API Timeout**       | DonorPerfect API unavailable        | Retry with backoff delay             |

## API Operations

### DonorPerfect Gift Creation

<AccordionGroup>
  <Accordion title="dp_savegift Action">
    **Required Parameters**:

    ```
    @gift_id (empty for new gifts)
    @donor_id (required)
    @record_type = 'G'
    @gift_date (MM/DD/YYYY format)
    @amount (decimal dollars)
    @gl_code (must exist)
    @user_id = 'WeGive'
    ```
  </Accordion>

  <Accordion title="Optional Parameters">
    **Additional Fields**:

    ```
    @pledge_payment ('Y' or 'N')
    @memory_honor (tribute name)
    @gift_narrative (description)
    @currency (currency code)
    ```
  </Accordion>
</AccordionGroup>

### Query Operations

<AccordionGroup>
  <Accordion title="Gift Lookup">
    **SQL Query Example**:

    ```sql theme={null}
    SELECT gift_id, donor_id, gift_date, amount, gl_code
    FROM dpgift 
    WHERE user_id = 'WeGive'
      AND gift_date >= 'MM/DD/YYYY'
    ORDER BY gift_id DESC
    ```
  </Accordion>
</AccordionGroup>

## Sync Configuration

### Transaction Sync Settings

<AccordionGroup>
  <Accordion title="Sync Triggers">
    **Automatic Sync Events**:

    * New transaction created in WeGive
    * Transaction status changes (completed, failed, refunded)
    * Recurring donation payment processed
    * Fund designation changes
  </Accordion>

  <Accordion title="Sync Timing">
    **Processing Schedule**:

    * **Real-time**: New donations sync immediately
    * **Batch Processing**: Failed transactions retry every 15 minutes
    * **Manual Sync**: Available through dashboard
    * **Error Recovery**: Exponential backoff for failures
  </Accordion>
</AccordionGroup>

### Performance Considerations

<CardGroup cols={2}>
  <Card title="High Volume Processing" icon="gauge-high">
    * Batch processing for multiple transactions
    * Rate limiting to prevent API overload
    * Queue management for peak periods
    * Automatic retry for failed syncs
  </Card>

  <Card title="Error Recovery" icon="refresh">
    * Failed transactions automatically retry
    * Exponential backoff prevents system overload
    * Manual retry options in dashboard
    * Comprehensive error logging
  </Card>
</CardGroup>

## Data Quality and Validation

### Pre-Sync Validation

<AccordionGroup>
  <Accordion title="Required Field Checks">
    **Validation Rules**:

    * Donor ID must exist in DonorPerfect
    * Transaction amount must be positive
    * Fund GL code must be valid
    * Date must be in correct format
    * Currency code must be recognized
  </Accordion>

  <Accordion title="Data Quality Checks">
    **Automatic Corrections**:

    * Date format standardization
    * Amount precision correction
    * GL code validation and creation
    * Donor profile auto-creation
  </Accordion>
</AccordionGroup>

### Monitoring and Reporting

<AccordionGroup>
  <Accordion title="Sync Status Tracking">
    **Dashboard Metrics**:

    * Transaction sync success rate
    * Average sync processing time
    * Error rate and common failure types
    * Pending transaction queue status
  </Accordion>

  <Accordion title="Financial Reconciliation">
    **Accuracy Verification**:

    * Total amount comparisons
    * Fee calculation verification
    * Fund distribution accuracy
    * Currency conversion validation
  </Accordion>
</AccordionGroup>

## Troubleshooting

### Common Transaction Sync Issues

<AccordionGroup>
  <Accordion title="Transactions Not Syncing">
    **Possible Causes**:

    * Transaction sync disabled in configuration
    * Donor missing from DonorPerfect
    * Invalid fund GL code
    * API authentication problems

    **Solutions**:

    * Verify sync configuration enabled
    * Check donor sync status
    * Validate fund GL code setup
    * Test API credentials
  </Accordion>

  <Accordion title="Incorrect Amounts">
    **Possible Causes**:

    * Fee calculation errors
    * Currency conversion issues
    * Rounding precision problems

    **Solutions**:

    * Review fee configuration
    * Check currency settings
    * Verify amount calculation logic
  </Accordion>

  <Accordion title="Missing Tribute Information">
    **Possible Causes**:

    * Tribute name exceeds field length
    * Special characters in tribute name
    * Tribute type not supported

    **Solutions**:

    * Truncate long tribute names
    * Remove special characters
    * Use tribute name field only
  </Accordion>
</AccordionGroup>

## Related Documentation

<CardGroup cols={2}>
  <Card title="Donor Mapping" href="/donorperfect/data-mapping/donor">
    Learn how donor records are synchronized
  </Card>

  <Card title="Recurring Donations" href="/donorperfect/data-mapping/recurring-donation">
    Understand recurring gift and pledge mapping
  </Card>

  <Card title="Fund Management" href="/donorperfect/data-mapping/fund">
    GL code and fund designation mapping
  </Card>

  <Card title="Configuration Guide" href="/donorperfect/configuration-options">
    Configure transaction sync settings
  </Card>
</CardGroup>

For additional help with transaction data mapping, contact our support team at [support@wegive.com](mailto:support@wegive.com).