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

> Detailed mapping between WeGive transactions and Bloomerang transaction records

# Transaction Mapping

This document provides comprehensive mapping details between WeGive transaction objects and Bloomerang transaction records, including donations, payments, and fund designations.

## Overview

Bloomerang uses the **Transaction** 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.

## Core Transaction Mapping

### Primary Fields

| WeGive Field        | Bloomerang Field | Type     | Required | Transformation                     |
| ------------------- | ---------------- | -------- | -------- | ---------------------------------- |
| `id`                | Correlation ID   | String   | No       | Stored in WeGive `bloomerang_id`   |
| `amount`            | `Amount`         | Decimal  | Yes      | Cents to dollars (÷100)            |
| `created_at`        | `Date`           | DateTime | Yes      | UTC to organization timezone       |
| `owner` (donor\_id) | `AccountId`      | Integer  | Yes      | Linked constituent ID              |
| `status`            | `IsRefunded`     | Boolean  | No       | Success=false, Refunded=true       |
| `source_type`       | `Method`         | String   | No       | Payment method mapping             |
| `fee_amount`        | `Fee`            | Decimal  | No       | Processing fees (cents to dollars) |

### Extended Fields

| WeGive Field | Bloomerang Field         | Transformation   | Notes                          |
| ------------ | ------------------------ | ---------------- | ------------------------------ |
| `currency`   | `CurrencyCode`           | Direct mapping   | Defaults to USD                |
| `reference`  | `CreditNote`             | Reference number | Transaction ID or check number |
| `memo`       | `Note`                   | Direct mapping   | Internal notes or memo         |
| `fund_id`    | `Designations[0].FundId` | Fund correlation | Primary fund designation       |

## Transaction Types

### Donation Transactions

**Standard Donation Behavior:**

When a donation is processed in WeGive, the transaction information syncs to Bloomerang with:

* **Amount Conversion**: Amounts stored in cents in WeGive convert to dollars in Bloomerang
* **Timezone Handling**: Transaction timestamps convert from UTC to your organization's timezone
* **Payment Method Mapping**: Payment types map to appropriate Bloomerang methods
* **Fee Tracking**: Processing fees sync separately when available
* **Fund Assignment**: Donations link to the appropriate fund or default fund

### Recurring Donation Transactions

**Recurring Gift Processing:**

Recurring donations from WeGive sync to Bloomerang with:

* **Recurring Status**: Transactions are marked as recurring in Bloomerang
* **Schedule Connection**: Links to the recurring donation schedule
* **Payment Method**: Bank transfers typically used for recurring gifts
* **Fund Assignment**: Consistent designation across all recurring payments
* **Transaction History**: Each recurring payment creates a separate transaction record

## Payment Method Mapping

### Source Type Transformation

| WeGive Source Type | Bloomerang Method | Description                       |
| ------------------ | ----------------- | --------------------------------- |
| `card`             | `CreditCard`      | Credit/debit card payments        |
| `bank`             | `EFT`             | Electronic fund transfers/ACH     |
| `check`            | `Check`           | Check payments                    |
| `cash`             | `Cash`            | Cash donations                    |
| `venmo`            | `CreditCard`      | Venmo payments (treated as card)  |
| `paypal`           | `CreditCard`      | PayPal payments (treated as card) |
| `crypto`           | `None`            | Cryptocurrency donations          |
| `stock`            | `Stock`           | Stock/securities donations        |
| `other`            | `None`            | Unknown or other methods          |

### Payment Method Processing

The system automatically maps WeGive payment types to the appropriate Bloomerang payment methods, ensuring consistent categorization across both platforms.

## Fund Designation Mapping

### Single Fund Designation

**Simple Fund Assignment:**

When a transaction has a single fund designation:

* The transaction amount is assigned entirely to the specified fund
* WeGive fund IDs are mapped to corresponding Bloomerang fund IDs
* Anonymous designation settings are preserved when available

### Multiple Fund Allocations

**Split Designations:**

When a transaction is split across multiple funds:

* Each fund allocation creates a separate designation in Bloomerang
* Individual amounts are preserved for each fund
* The sum of all designations equals the total transaction amount
* Fund mapping maintains the connection between WeGive and Bloomerang funds

### Default Fund Handling

**No Fund Specified:**

When a transaction doesn't have a specific fund designation:

* The transaction is automatically assigned to your organization's default fund
* This ensures all transactions have proper fund designations in Bloomerang
* The default fund can be configured in your integration settings

## Data Transformation

### Amount Processing

**Currency Conversion:**

* WeGive stores amounts in cents for precision
* Bloomerang uses dollar amounts with two decimal places
* Conversion happens automatically during sync
* Ensures accuracy for all financial calculations

### Date Processing

**Timezone Conversion:**

* Transaction dates in WeGive are stored in UTC
* Bloomerang receives dates in your organization's local timezone
* Automatic conversion ensures dates display correctly in both systems
* Time zone settings are managed in your organization profile

### Status Mapping

**Transaction Status Processing:**

* Successful transactions sync as normal donations
* Refunded transactions are marked as refunded in Bloomerang
* Partial refunds include notes explaining the refund status
* Failed or canceled transactions do not sync to maintain clean records

## Sync Operations

### Push Operation (WeGive → Bloomerang)

**Creating Transactions:**

When a transaction is created in WeGive, the sync process:

* Ensures the donor exists as a constituent in Bloomerang
* Converts amounts from cents to dollars
* Adjusts timestamps to your organization's timezone
* Maps payment methods to Bloomerang categories
* Assigns fund designations or uses the default fund
* Includes processing fees, notes, and reference numbers when available
* Handles refund status appropriately
* Links the transaction records between both systems

### Pull Operation (Bloomerang → WeGive)

**Importing Transactions:**

When importing transactions from Bloomerang into WeGive:

* Finds or creates the corresponding donor record
* Converts dollar amounts to cents for WeGive storage
* Adjusts timestamps from organization timezone to UTC
* Maps Bloomerang payment methods to WeGive categories
* Imports refund status and transaction notes
* Links fund designations to WeGive funds
* Includes processing fees and reference information
* Maintains connection between the systems for future updates

## Transaction Categories

### Transaction Type Mapping

**Transaction Type Mapping:**

Bloomerang transaction types automatically map to corresponding WeGive categories:

* **Donation**: Standard one-time donations
* **PledgePayment**: Payments toward pledges
* **RecurringDonation**: Recurring/subscription donations
* **Grant**: Grant funding
* **InKind**: In-kind donations
* **Membership**: Membership fees
* **Other**: Miscellaneous transactions

### Special Transaction Handling

**Pledge Payments:**

* Transactions linked to pledges maintain their connection across both systems
* When a pledge exists, payments are properly categorized as pledge payments
* If no pledge connection is found, transactions are treated as regular donations
* Pledge relationships preserve donor commitment tracking

**Recurring Donations:**

* Recurring transactions maintain links to their recurring donation schedules
* Each recurring payment is processed as an individual transaction
* Schedule information syncs to maintain donor subscription details
* Recurring patterns are preserved across both platforms

## Validation and Error Handling

### Data Validation

**Required Field Validation:**

Transactions must meet these requirements to sync successfully:

* **Constituent Connection**: Transaction must be linked to an existing constituent
* **Valid Amount**: Transaction amount must be greater than zero
* **Transaction Date**: A valid transaction date is required
* **Fund Designation**: At least one fund designation must be specified

### Common Validation Issues

**Missing Constituent:**

* If a transaction's donor doesn't exist in Bloomerang, the system automatically creates the constituent first
* This ensures all transactions have valid donor connections
* Constituent creation happens seamlessly during transaction sync

**Invalid Fund Mapping:**

* If a specified fund doesn't exist in Bloomerang, the transaction uses your default fund
* This prevents transaction sync failures due to fund mapping issues
* Fund mappings can be configured in your integration settings

## Sync Performance and Reliability

### Batch Processing

**Efficient Synchronization:**

* Transactions sync in optimized batches for better performance
* Large volumes of transactions are processed in manageable chunks
* System includes automatic rate limiting to respect API constraints
* Failed transactions are logged and can be retried

### Data Consistency

**Reliable Fund Mapping:**

* Fund mappings are cached to improve sync performance
* System maintains accurate connections between WeGive and Bloomerang funds
* Automatic fallback to default funds prevents sync failures
* Regular validation ensures data quality across both platforms

### Sync Monitoring

**Transaction Sync Tracking:**

* All sync operations are logged with detailed status information
* Success and error states are tracked for each transaction
* Transaction metadata includes amounts, IDs, and fund information
* Comprehensive logging enables troubleshooting and audit trails

This transaction mapping ensures accurate financial data synchronization between WeGive and Bloomerang while maintaining transaction integrity and proper fund accounting across both platforms.