Aller directement à la fin des métadonnées
Aller au début des métadonnées

Phase 1 Scope / Assumptions

CiviContribute Phase 1 will support the following functionality:

  • Define custom fields to extend the core Contribution class (custom fields are available for import, export, online Donation Pages and 'offline' Contribution input forms)
  • Configure any number of contribution types (e.g. Charitable Donations, Campaign Contributions, Membership Fees, etc.)
  • Import and Export Contribution records
  • Basic Contribution Search/Listings (search and list contributions by date range, amount range, type etc.)
  • Support for one or more configurable Donation Pages for online donations - each page can include configurable intro text, thank-you message, and any core and custom CiviCRM fields.
  • Each Donation Page can have it's own set of amount options, and/or open-ended amount input field (with configurable minimum and maximum values allowed)
  • Online Donations will support PayPal Express or PayPal Pro payment gateway/API
  • Option to allow credit card payment method only
  • Payment Processor is responsible for storage / retrieval of transaction details - CiviDonate will store transaction identifiers (foreign key to processor record/details)
  • Automatic email receipting with configurable message
  • Online donations create CiviCRM contacts, or associates donation w/ existing contact (based on configurable matching rules)
  • Ability to reverse-out a Contribution manually (inserts new reversal financial transaction record and updates Contribution status to 'cancelled')

The following features are being considered for subsequent phases (and are NOT part of phase 1):

  • Donation Pages are linked to one or more Projects/Campaigns
  • Option to use CAPTCHA on Online Donation Pages to prevent scripting attacks
  • Account information may be persisted (e.g. financial institution routing/transit, account numbers, etc.)
  • Recurring Contributions
  • Renewing/Time-delimited Memberships
  • Premiums (thank-you contributions)
  • Automatic calculation of deductible amount of total contribution based on donation page setting for overall deductibility AND market value of any premium(s)
  • Option to ask donor if they want to increase their donation amount to cover processing fees (and auto-calc new amount if yes)
  • Pledges (recording and tracking)
  • Matching Grants
  • Processors other than PayPal
  • Tell a Friend
  • Integrated chargeback (for phase 1, site owners will use PayPal interface for chargeback credits)
  • Accounting Package integration

Menu / User Interface Elements

Phase 1 Menu/UI will include basic search for contributions - with export, add/edit forms for manual input, import of contribution records, and configuration of online donation pages. Online donation pages can be rendered within the CMS framework using a generated link (and hence linked from anywhere on the site). We will also generate HTML code for any configured donation page which can be pasted into any web page.

CiviContribute Menu

  • Find Contributions
  • Import Contributions
  • Configure Online Contribution Pages

Find Contributions

Basic search screen plus listings (selector table). Searches for Contributions on the following criteria:

  • Contact Name (partial or full)
  • Contribution Date : From / To
  • Amount: Min / Max
  • Contribution Type: (multi-select checkbox group populated from contribute_type table - see below; e.g. Campaign Contribution, Membership Dues...)
  • Payment Instrument: (multi-select checkbox group populated from payment_instrument table - see below; e.g. Cash, Check, Credit Card...)
  • Contribution Status: (radio, default = Valid, Cancelled, All)

Results (listings) are sortable by each column and include:

  • Name
  • Contribution Type
  • Payment Instrument
  • Amount
  • Contribution Date
  • Thank-you Date
  • Cancel Date

Row-level Actions = View, Edit, Cancel, Delete (depending on permissions - TBD)

The search criteria display included in the search results should include a Totals section which returns the number of matching contributions and the Grand Total Amount for the resultset.

The "New Contribution" action will definitely be available from the individual contact pages. The workflow for entering a new contribution from the CiviDonate landing page may be deferred until phase 2 since we need an easy way for the user to find the contact associated with the new contribution within this workflow (probably best implemented as an Ajax auto-complete type search).

Batch level (selector) Actions for Phase 1:

  • Export Contributions
  • Print Contributions
  • Delete Contributions (??)

Probably should not allow edit or delete of Online Contributions ??

Export Contributions

For phase 1 we will have a 'standard' export which will output all core and custom Contribution fields plus donor identifying fields:

  • contact_id
  • contact name fields (first, middle, last)
  • contact email

Add / Edit / View Contribution

  • Form / page exposes all core and custom Contribution properties (see below)
  • On add/edit - an corresponding Activity History record should be inserted (see online donation example below)

Cancel Contribution

  • View Contribution page PLUS simple form with single field to enter Cancellation Reason.
  • On submit:
    • Update Contribution record by setting cancel_date_time and cancel_reason
    • Insert Activity History record for cancellation (refer to column mappings in Online Donation Processing section below)
    • Check for linked Electronic Financial Transaction record (with type = DEBIT) - and insert reversing record (type = CREDIT) if one exists

Import Contributions

  • Phase 1 import supports import of Contribution records only. Core and custom contribution fields are mapped (same flow as current Contact Import Wizard).
  • Import REQUIRES that incoming rows include the CiviCRM contact_id (primary key) of the donor

NOTE: Existing contact Export functionality will be extended to provide the contact_id's.

CiviContribute Access Control

For Phase 1, we will add the following access control permissions which can be assigned to Roles as needed:

  • access CiviContribute (global access to CiviContribute menus)
  • edit contributions (CRUD access to contribution records)
  • view contributions (read-only access to contrib records, includes search and export)

Contact access permissions will intersect with these permissions. So, if user A only has permission to'view contacts in New York Members' group - and they are granted 'view contributions' - they would only see contributions for contacts in the NY Members group.

Configure Contribution Pages

Each domain may have 1 : n Contribution Pages. Contribution Pages are 'built' from an introductory block, a fixed set of required donation-specific fields, plus two optional Profile (UF_Group) objects - one of which can be positioned before the required 'donation fields' block, and one which can be positioned after.
*Introductory Block: *

  • Title - Optional 'headline' for the Donation Page
  • Introduction - (text type column) May contain HTML layout (and therefore may include logos and other images by reference).

Required Contribution Fields:

  • Contribution Amount (configurable radio button array with option to include Other Amount open input field and to set min and max amounts allowed)
  • First, Middle, Last Name
  • Billing Address block (includes Location Type selector)
  • Email Address
  • Card Type
  • Expiration Date
  • CVV2 Code

Billing Address specification:
A new flag (is_billing) will be added to the Location class (and assigned by default to a contact's primary location). Addresses acquired from a Donation Page billing address block will be flagged is_billing. Existing contacts should have the ability to select one of their existing locations and mark it as their billing address OR enter a new location which will be then flagged is_billing.

User-defined Profile (Group) objects:
One pre- and one post-donation block profile can be configured for a given Donation Page. Each profile defines a fieldset which can collect data for any available core OR custom Contact or Git property. For example, you could create a 'Tell Us About Yourself' profile which collects core properties like Date of Birth, Gender, etc as well as custom contact fields (e.g. Voting Precinct, Marital Status, etc.). And/or you could create a 'Contribution Info' profile which collects contribution (transaction) specific data (e.g. Donation in Memory Of, Donation in Support of...).

Profiles are linked to a Donation Page via ModuleProfile class (see below)

1. Classes / Schemas

1.1 ModuleProfile

This 'join table' links modules (and sometimes module entities) to profiles (uf_group records). Modules like CiviDonate will aggregate the profiles needed to render a particular Donation Page from this table.

  • id
  • domain_id
  • module (string; required; e.g. CiviDonate, User, Volunteer)
  • entity_table (string; optional; 'civicrm_contribution_page' for CiviDonate, null for 'User')
  • entity_id (int; optional FK; for CiviDonate, null for 'User')
  • uf_group_id (FK to a profile)
  • weight (int; each internal or external module uses this to order multiple profiles associated w/ an entity_id)


  • Contribution Page:
    SELECT uf_group_id FROM module_profile WHERE entity_table = 'civicrm_contribution_page' AND entity_id = '$contribution_page_id'
  • Account Registration (User module does not use entity_table/id):
    SELECT uf_group_id FROM module_profile WHERE module = 'User' ORDER BY weight
  • For Contribtion Pages, weighting will be 'hard-coded' with weight=1 meaning Profile is rendered BEFORE required donation fieldset, and weight=2 rendered below the donation fieldset.
  • For Account Registration / My Account ('User' module) - we will migrate existing civicrm_uf_group.weight values into civicrm_module_profile.weight when we upgrade existing DB's. And then expose the join table weight values when viewing Profiles under Administer CiviCRM (admin/uf/group).
1.2 ContributionPage

Represents a specific instance of an online donation form.

  • id
  • domain_id
  • title (string; required; for top of page display)
  • intro_text (text; optional; text and html allowed, displayed in <div> below title)
  • contribution_type_id (int; FK; default Contribution type assigned to contributions submitted via this page, e.g. Donation, Campaign Contribution... see ContributionType below)
  • is_credit_card_only (boolean; required; default = false; if true - donation processing logic must reject transaction at confirmation stage if pay method != credit card)
  • amount_field_id (int; optional; FK to civicrm_custom_field record which is used for the donation amount)
  • is_allow_other_amount (boolean; default=False; if true, page will include an input text field where user can enter their own donation amount)
  • min_contribution_amount (decimal 20,2; optional; if other amounts allowed, user can configure minimum allowed)
  • max_contribution_amount (decimal 20,2; optional; if other amounts allowed, user can configure maximum allowed)
  • thankyou_text (text; optional; text and html allowed; displayed above donation 'results' on 'success' page)
  • is_email_receipt (boolean; default = true - receipt is automatically emailed to donor on success)
  • cc_receipt (string; optional; comma-separated list of email addresses to cc each time a receipt is sent)
  • bcc_receipt (string; optional; comma-separated list of email addresses to bcc each time a receipt is sent)
  • receipt_text (text; optional; text to include above standard receipt info on receipt email; emails are text-only, so do not allow html for now)
  • is_active (boolean)

2. Pages and Forms

2.1 Configure Contribution Pages

This page as a listing of existing pages and several links (below the selector table):

  • Listing columns:
    Title, Contribution Type, Donate Link, Status, Actions
  • Actions = Configure, Preview, Standalone Form, Disable, Delete.
  • "Donate Link" column contains URL to load that donation page within the CMS framework
  • "Standalone Form" action goes to a page with textarea containing HTML to render this complete donation page (display text, form elements, etc.). This is similar to the new 1.2 functionality for CiviCRM Profiles.
  • Below selector table:
    >> New Donation Page
2.2 Configure Contribution Page

This page is basically a 'menu' with a set of links to various configuration tasks. Items are:

2.2.1 Donation Page Settings
Links to Edit form containing the following fields:

  • Title
  • Contribution Type (drop-down)
  • Credit Card Payments Only? (radio yes/no)
  • Introductory Message (large textarea - 6 rows)
  • Active?

2.2.2 Thank-you and Receipting
Links to Edit form with the following fields:

  • Thank You Message (large textarea - 6 rows)
  • Email Receipt to Donor? (radio yes/no)
  • CC Receipt to
  • Receipt Message (small textarea - 2 rows)

2.2.3 Contribution Amounts

Llinks to page for creating / editing array of up to 11 (arbitrary limit) donation level labels/amounts (see Issue above) - preceded by the following fields:

  • Allow Other Amounts? (radio yes/no)
    • If allow_other_amount = yes, unhide the next 2 fields
  • Minimum Contribution Amount
  • Maximum Contribution Amount
  • Contribution Amount Options (this is a fieldset for editing the array of options - shares code w/ custom field option editing for a new custom field with type = radio)
  • We will insert a 'special' custom field for each donation page which has custom_group_id = 0. It is linked to the page via donate_page.amount_field_id.
  • If Allow Other Amounts is true, then no Contribution Amount Options are required. Else, user must create at least 1 contribution amount option.
  • User needs to be able to set / modify order of amount options, and optionally set a default choice. Initially, display 5 option rows - with link to show more.

2.2.4 Custom Page Elements:
Links to an Edit form containing:

  • Include this Profile ABOVE the required donation fields:
    (drop-down allows selection of any existing Profile UF_Group; field value is a property of the module_profile record linked to this donation_page and with weight = 1)
  • Include this Profile BELOW the required donation fields:
    (drop-down allows selection of any existing Profile UF_Group; field value is a property of the module_profile record linked to this donation_page and with weight = 2)
  • >> Create New Profile for this Donation Page' (links to uf/group?action=add; with additional parameters which result in the new profile getting linked to this donation page in module_profile when it is saved).

NOTE: There are some additional navigation issues to work out here - especially with regard to how user gets back to configuring donation page if they've gone off to create a new profile. It would also be useful to give them a way to preview profile(s) from this screen. We could put a button next to each profile drop-down -> Preview Selected Profile. This would take them to a new page which previews (renders) the selected profile (and includes a >> Back link).

2.3 Preview Contribution Page

Provides a 'preview' of the complete Donation Page as it will be rendered to the donor (with an extra <div class="message"> above and below clarifying that this is a preview).

2.4 Contribution Page Flow

*User completes form fields on donation page (within CMS framework OR standalone)

  • Submitted form is validated for required fields, valid credit card hash, etc.
    • If donation_page.credit_card_only is true, return validation error if PayPal payment method != credit card (e.g. don't allow 'PayPal Account' payments)
  • Display Confirmation page with summary of contribution info (including 'masked' card number) - and choice to 'Complete Donation' or 'Change Donation Information'
  • Display Success/Thank-you Page OR Error Page

NOTE: For PayPal Express - user will be redirected to PayPal pages to select billing account, etc. prior to Confirmation step.

Configure Payment Processor

For this phase, we will support a single processor per 'site' and configuration will be stored in using the following constants:

  • PROCESSOR (phase 1 options are 'PayPal Direct' and 'PayPal Express'; this value will determine main function call for payment processor integration)
  • CONFIG_FILE_PATH (for PayPal, account identifier and encryption stuff is stored in a file which they generate)

NOTE: These are the values needed for the PayPal integration. We anticipate adding (and possibly modifying) settings to handle alternative processors in subsequent phases (and/or as we get contributors working on other processor integrations).

Classes / Schema for Online and Offline Contributions


Admin configurable table of enum values. Prepopulate with Donation, Member Dues, Campaign Contribution. Can set up types for non-monetary contributions as well (e.g. Volunteer Services, Hard-goods Contribution, etc.).

  • id
  • domain_id
  • name
  • description
  • accounting_code (string; optional mapping to accounting system code for this type/category of contribution)
  • is_deductible (boolean; default=true; Is this contribution type tax-deductible? If true, contributions of this type may be fully OR partially deductible - non-deductible amount is stored in the Contribution record.)
  • is_reserved (boolean; default=false)
  • is_active

Admin configurable table of enum values. Prepopulate with Credit Card | Debit Card | Check | Cash | EFT etc

  • id
  • domain_id
  • name
  • description
  • is_reserved (boolean; default=false)
  • is_active

All online and offline 'donations' are recorded as a Contribution object. All contributions are linked to a newly created or existing contact record.

  • id
  • domain_id
  • contact_id (FK to Contact record of donor)
  • entered_by_contact_id (int; required; FK to contact who entered/imported contribution record for offline contributions; FK to the donor for online contributions)
  • contribution_type_id (int; optional; FK to contribution_type; value derived from donation_page for online donations)
  • payment_instrument_id (int; required; FK to payment_instrument)
  • received_ date (date-time; required; When was contribution received)
  • trxn_id (string; required; unique key; processor transaction id, bank+bank trans id, account+check number... depending on payment_method)
  • total_amount (decimal 20,2; required; Total amount of this contribution. Use market value for non-monetary gifts.)
  • fee_amount (decimal 20,2; required; actual processor fee if known - may be 0)
  • net_amount (decimal 20,2; required; total less fees; if processor doesn't report actual fee during transaction, this is set to total_amount)
  • non_deductible_amount (decimal 20,2; required; Portion of total amount which is NOT tax deductible. Equal to total_amount for non-deductible contribution types.)
  • currency (string; Value derived from payment processor config setting)
  • cancel_date (date-time; Null unless contribution was cancelled)
  • cancel_reason (string; optional)
  • receipt_date (date-time; optional; When (if) receipt was sent; populated automatically for online donations w/ automatic receipting)
  • thank_you_date (date-time; optional, When (if) was donor thanked)
  • source (string; optional; For online donations, populate with Donation Page title; else populate via input form or import mapping)

For online contributions in phase 1, non_deductible_amount is set to 0 if contribution type for the donation page is tax deductible. Else, it is set equal to total_amount (this will be more flexible when we introduce premiums which affect deductible amounts in a later phase). For offline contributions, total amount and non-deductible amount can be set independently via edit screens or import.

Thank-you date could be handled as a custom field, but if we need to create workflows for donor follow-ups (likely) - it seems better to have it in core.


All Contributions successfully generated via an electronic transaction will have one or more associated Financial Transaction records. Each interaction with the payment processor will be recorded separately. A donation followed by a chargeback (cancellation) would be represented by two separate records. For this phase, we will NOT record a transaction record for interactions which do not actually move funds (e.g. authorization).

Failed transactions (invalid expired cards, bad CVV2, etc.) will not be recorded here (at least for phase 1). We will create an Activity History record which can link to details via the payment processors' API.

This table is designed to store transactions related to other eCommerce (non-contribution) applications in the future (e.g. conference/event fees, hard-goods purchases, etc.).

  • id
  • domain_id
  • entity_table (string; required; always 'civicrm_contribution' for now; later we can link to other types of commerce transactions like event fees, hard goods purchases, etc.)
  • entity_id (int; required; FK to entity_table)
  • trxn_date_time (date-time, required)
  • trxn_type (enum; required; Debit = money received from donor/payee; Credit = money reimbursed to donor or payee)
  • total_amount (decimal 20,2; amount of contribution)
  • fee_amount (decimal 20,2; required; actual processor fee if known - may be 0)
  • net_amount (decimal 20,2; required; actual funds transfer amount; total less fees; if processor doesn't report actual fee during transaction, this is set to total_amount)
  • payment_processor (string; required; derived from Processor setting in
  • trxn_id (string; required; processor transaction id or bank r/t+bank trans id... depending on payment_method)
  • trxn_result_code (string; optional; processor result code)

Online Contribution Processing

1. PayPal Integration

CiviDonate architecture will support development of plugins for a variety of payment gateways. We will be delivering a PayPal plugin for phase 1.


  • Support both PayPal Express (use donor's PayPal-stored account info), and Pro processing
  • Log every transaction (auth, charge, credit) - successes and failures, with PayPal transaction ID and result/error code(s).
  • Acquire contact data (name, address, etc.) for storage in CiviCRM
  • Do NOT persist credit card data (blow away any info in session as soon as possible)

2. Record Contribution/Payment Results

2.1 Execute the following steps for each SUCCESSFULLY completed online donation:
  • If we have a contact handle (e.g. donation by logged in user), update contact name and address fields as needed
  • If we don't have a contact handle, check for matching contact record (based on configured duplicate match rules)
    • Insert new contact if no match
    • Else update existing contact
  • Insert Contribution record
  • Insert Electronic Financial Transaction record
  • Insert Activity History record
    • entity_table = civicrm_contact
    • entity_id = contact_id
    • activity_type =
    • module = CiviDonate
    • callback = (function to display Contribution details)
    • activity_id = PK of new Contribution record
    • activity_summary = "$method - $xxx.xx - $"
      EXAMPLES: "Online - $150.00 - money"; "Offline - $1,000.00 - Services"
  • Generate and send receipt email (if enabled in Donation Page)
2.2 Execute the following steps for each FAILED online donation session (invalid card, exp date, etc.):
  • If we have a contact handle (e.g. donation by logged in user), update contact name and address fields as needed
  • If we don't have a contact handle, check for matching contact record (based on configured duplicate match rules)
    • Insert new contact if no match
    • Else update existing contact
  • Insert Activity History record
    • entity_table = civicrm_contact
    • entity_id = contact_id
    • activity_type = + 'Failure'
    • module = CiviDonate
    • callback = (function to display transaction details via Processor API)
    • activity_id = processor transaction identifier
    • activity_summary = "'Failed online contribution -' + $xxx.xx + 'Error: ' + $processor_failure_reason"
      EXAMPLE: "Failed online contribution - $50.00. Error: invalid exp date"
2.3 Components of Email / Web Receipt
  • Web 'receipt' is displayed on Thank-you page following configured thank-you message.
  • Email 'receipt' is output in donor email following configured receipt message.
  • Both contain the following:
    (receipt contents TBD)

Custom Data Enhancements and Related Profile Changes

Custom Groups will now be able to 'extend' Contribution or Activity (in addition to existing options to extend Contact, Individual....Location...).


Profile Enhancements

Profile Preview and Profile support for multiple locations, phones, etc;


  • Aucun
  1. Sep 14, 2005

    j. brush dit :

    couple small points, and a big one: i thought about editing wiki directly, but not sure of protocol on that

    1. you're using "credit" and "debit" the inverse of standard accounting procedure. normally money into an asset account is a "debit", and money out is a "credit". this is confusing because of banks' usage, from their perspective. perhaps make this optional, or at least clear?

    2. it seems you're missing "amount each period" from pledge.

    big issue:

    biggest challenge seems to design data structure and api so allow for effective integration with accounting software. in the open source world, i think that means sql-ledger primarily, but nonprofits may have commercial or custom accounting software, or may use quickbooks etc. in any event, some mechanism either to export in appropriate format, or (much better) to automatically connect with an accounting database (here esp. thinking of sql-ledger) and insert records (that would probably have to be approved), would be really valuable.

    here i'm thinking that one could, in sql-ledger, have an "import from civicrm" button inserted, that connected with the civicrm db and updated accounts. ... minimal modification (ie,. not full integration) but extremely time-saving.

    ideas? suggestions?

  2. Sep 14, 2005

    JoeMurray dit :

    1. I agree that having an api for an accounting package to link to/ hooks to link into an accounting package api is essential.

    2. I wouldn't recommend tracking non-online donations through a manual interface as a priority, since that implies the transactions have to be manually entered into both the NGO's accounting software and CivicCRM. Better to focus on creating a good import API for non-online donations so that CivicCRM can start to be used for making decisions around the relationship management based on all available historical data.

    3. Linking a gift to a campaign is minimal. I'm wondering about being able to have landing pages on the website that are customized to 1) a campaign, and 2) the donor. That means the organization can solicit funds via email appeals for more than one purpose at a time - its a bit amateur to have all donations through a single generic page. And it's very important to tailor the suggested donation amounts based on past giving history.

    Joe Murray
    JMA Consulting

  3. Sep 14, 2005

    I fixed the spec based on brush's comments. Added interface to sql-ledger / quickbooks as a goal, not sure what is involved, but agree that we need to tackle and address this

    joe: there is a discussion on the crm-dev list on the importance of offline tracking. I suspect this is super important to quite a few folks in the community

    we have not yet speced out donation page functionality. but yeah having multiple landing pages that are customized to the campaign / donor is definitely a requirement. We are envisioning the system to be similar to DonateNow with support for different pages/campaign etc


  4. Sep 14, 2005

    Some thoughts – we work primarily with grassroots organizations, most of which could be more savvy but aren't yet about making sure that volunteer hours are noted as a tax-deductible contribution of services to a 501c3 organization.

    The groups LINC provides technology assistance to are fairly consistently interested in tracking member engagement to identify leaders and recruit active members into leadership roles – they want to be able to keep track of who has said they will come to an event (an action, phone banking, a training) and use their database to share RSVP info about events – how many people are planning to attend, who should get a follow up call.

    Meanwhile, on donations ... the groups we work with want to be able to interact with donations in a few ways:

    • Dues processing: at the last membership meeting someone collected dues. a staff person responsible for data entry sits down and goes through the stack of checks recording payments and updating addresses where necessary. Somehow (magic?) all the relevant data makes it into quick books as well. In fantasy land, when they installed the database that link was somehow integrated and they don't have to touch it. Realistically, I think some checks and balances are not unreasonable, so either:

    Organizer updates database, exports a spreadsheet of recent payments that she can import into quickbooks (so civicrm would need to ask for all of the fields that quickbooks is going to need) or

    Organizer inputs dues payments in Quickbooks, and exports a list that includes those payments he just entered, and then imports those payments into civicrm so that they appear as dues payments.

    A week later, an organizer who is supposed to organize the board election process needs a list of current members whose dues are paid up. Somehow the organizer is able to conduct a search for members in good standing who are identified as 1) members and who 2) have paid dues for the last six months.

    • Website donations: a visitor to the website decides to give the organization $100. The donation and the individuals contact information are recorded and the donation is processed via paypal. In our world the rest doesn't need to be especially integrated into the system, but at the very least someone should be notified to perform the remaining tasks – send a thank you note/charitable receipt, import the donation into quickbooks. The individual is tagged as a "donor" or with another tag that the organization has identified for online donors.

    Very few groups we work with do extensive web based donation processing because for the most part their members don't have or use credit cards. Many of them do periodically send out appeal letters but most of the donations come back in the enclosed self-addressed envelope.

    What we really need first is the basic piece: either exporting a set of payments from quickbooks and pulling them into the database or just being able to add payments of a particular type (donation, dues, registration fee) and search for people who have (or have not) made payments recently.

  5. Sep 22, 2005

    Feature list from the Groundspring/ NFG comparison:

    Customization of logo/entire page layout
    User Administration Interface (allows editing of receipting, organizational information edited on site, etc)
    Electronic Funds Transfer options
    Editable donation forms (can change giving amounts and text)
    Recurring Donations
    Matching/Joint Donations
    Tribute Donations (i.e. make a donation in someone else's name)
    Premiums (Incentives for Giving)
    Tell a Friend
    Newsletter/Volunteer signup
    Not on giving pages but Volunteer signup is found on consumer site
    Custom questions of donors
    Customizable email/web thank you message
    Online summaries of donation totals
    Yearly and monthly comparisons
    Text file downloads of data (exports)
    Donor Fee to process transaction
    Event/Member Registration/ ticketing

  6. Oct 06, 2005

    JoeMurray dit :

    A small point: aome thought needs to be given to the difference between receiving a cheque for an offline donation, and having that cheque cleared by the bank. A reversal transaction with a reason that links to the original transaction would be one model.

    Joe Murray
    JMA Consulting

  7. Oct 07, 2005

    The model supports this explicitly by providing the ability to have multiple Financial Trxn instances (either Debits and/or Credits) linked to the same Gift.

    However, we'll need to think more about the workflow for entering checks. Should we automatically create the Debit trxn when the check is recorded (on the assumption that most will clear) - and then provide a way to reverse out the ones that bounce? This is probably the 'simple configuration' approach.

    Are there alternative workflows that will be needed - e.g. where the Debit transaction isn't triggered until an accounting transaction (funds deposited) is downloaded/recorded from the bank? Other flows?

    1. Oct 20, 2005

      JoeMurray dit :

      This should be sufficient to start at least. My client informs me that pre-authorized credit card payments also occasionally fail to come through in the end and need to be reversed.

  8. Oct 10, 2005

    To make donation campaigns successfull, they need to be as few clicks as possible and get all the legally necessary information — shouldn't require a donor to be a user of the site in order to donate, too many steps (but make them a user after they've donated) For example, federal campaigns need employer/occupation if over $210. These fields should be required depending on the amount given – but customizable, because state election laws differ. Also, should be able to alert user if they're recurring donation will put them above donation limits after x months.

    Contributed by Matt (mklaber at macalester dot edu)

  9. Oct 31, 2005

    Dan Robinson dit :

    Looks really good. I would like to see three additional features in the first release:

    1) Recurring payments - specified dates, periodically open-ended or date bounded.
    2) Tell-a-Friend
    3) API - I'm not clear from the spec if there will be an exposed API. The quicker this gets done the sooner folks will be able to do there own mods and possibly start contributing back.

    1. Nov 01, 2005

      Both Recurring Payments and Tell-a-Friend will probably get pushed to the second release as we are trying to get this first release out rapidly. Also, we're not clear on how we can support recurring payments without storing credit card numbers - and there's significant security issues to deal with going down that road. (triste)

      RE APIs - would be great to get some specific use case and the specific API calls these would required. Are we talking about 'simply' recording a contribution record, or ??

      1. Nov 02, 2005

        Dan Robinson dit :

        Good point about re-curring donations. This is something a lot of orgs ask for - but you are right - (and now I remember this conversation from the list earlier). I'll do more homework and get back to you.

        As for the API - a CRUD (Create, Read, Update, Delete) interface would be a good start, also a "batch" interface mode to get at multiple records (CRUD again). This should allow for the manipulation of the basic data at the API level

      2. Nov 22, 2005

        ted mcdonald dit :

        You shouldn't have to store credit card numbers. Convio allows recurring donations and also doesn't store the numbers. They say that the numbers are stored with the card processors.

  10. Nov 02, 2005

    I think Matt raises a good question about being as-few-clicks-as-possible, which makes me worry about having to rely upon PayPal.

    I've also heard some negative feedback about having donors having to use PayPal for donations. A couple of focus groups have noted that it doesn't seem "professional" and decreases their chance of donating to a non-profit. (Not a huge deal for me personally, but then again, I've never been a major donor).

    I've noticed that many of the MySQL/PHP e-commerce solutions allow for multiple different payment gateway options. Would it be possible in future versions to be able to have additional payment gateway options (,, etc.)?

    Seems like it could decrease the number of clicks and increase the comfort level for donors...

  11. Nov 02, 2005

    Cheryl Chase dit :

    I agree with Devin – I wouldn't use PayPal, because it gives an unprofessional appearance.

    Could you consider one of the npo proxy payments groups rather than paypal? (Groundspring, NFG).

    1. Nov 03, 2005

      RE: PayPal and Multiple Gateways

      • Our phase 1 work will support the new PayPal Pro/Direct service. This service requires a small monthly fee (I think it's $20 right now) - but allows folks to donate w/o ever going to the PayPal site. Licensing for this service also requires that a link is included to use the old-style PayPal interface - but only folks who want to use their existing PayPal account would go there. I suspect that most of the objections to PayPal are related to the original service (which pushed all donors to a PayPal website to complete their transaction).
      • We are architecting CiviDonate so that other payment gateway plug-ins can be swapped in. In fact, Joe Murray and Alan Dixon are already developing a Moneris plug-in which they've indicated should be ready at the same time that Phase 1 is released. We welcome others who would like to work with us on other gateways such as
  12. Nov 02, 2005

    Cheryl Chase dit :

    I don't see nondeductible amount in the spec for phase 1. Even though you aren't planning yet to support premiums, don't you need this for manually entered or imported gifts?

    1. Nov 03, 2005

      Cheryl - Great catch! We've added is__deductible to ContributionType, and a non_deductible_amount column to the actual Contribution record. If is_deductible is true, contributions of that type may be fully OR partially deductible - and non-deductible portion is stored in the Contribution record (will be 0.00 for fully deductible contributions).

  13. Nov 07, 2005

    Rich Cowan dit :

    Hi – everything looks great, but I just want to add key point. That is, there is an assumption in several of the posts (Joe Murray and Amanda Hickman) that an NGO is going to want to have each contribution entered separately into both their donation record keeping system and into Quickbooks.

    I want to question this assumption.

    If you have a good donor database, there should never be a need to duplicate the data entry and put all that info into Quickbooks. At almost every nonprofit I have worked at, the information you put into Quickbooks is just the aggregate totals, broken into categories, from a single batch of checks. (If your online donation system has direct deposit capability, then I would add "single day's worth of online gifts", but currently, our donation processor, Groundspring, does not.)

    Example: It is April and OC (Organizers' Collaborative) is about to have its annual conference. We go to the mailbox and receive 11 checks. 4 are for conference registrations ($140 total), 3 are membership renewals ($150 total), one is a check from Groundspring representing 3 new donors (2 at $50, 1 at $30) and 2 conference registrations ($130 + $70 - 3% processing fee) in March, 1 is a conference sponsorship ($125), and 2 are support fees for the Organizers Database ( ($30 and $50).

    What gets entered into quickbooks is a deposit that looks like this:

    Category Amount
    Conference:Registration $210
    Conference:Sponsorship $125
    Donation:Renewal $150
    Donation:New Membership $100
    Support-Train:ODB Supp Fee $80
    Fees:Online Services ($6.00) (groundspring, 3% of $200)
    TOTAL $659

    What you actually need – and I should add that this functionality is now supported by MissionResearch Giftworks, though I haven't tested it – is the ability to have categories in your online donation system that are mapped to QuickBooks categories.

    Automating this through CiviDonate would be great, but it is not an easy problem, because categorization of gifts is not that standardized. Sometimes an automated solution is not the best as it will allow bad data into your system due to the lack of a manual check (person in the loop). With Organizers Database ( we have not ventured there yet, because most orgs are dealing with 1-40 checks per deposit, not hundreds. But if we do, we would likely require that Quickbooks users have the "numeric accounting codes" option turned on, which would make the mapping a bit easier to tackle.

    Right now we provide a simple tool to assist an org. in its manual review. In the current development build of ODB (note: windows download only at this point), at:

    You can search for all the gifts entered on a particular date, and then click a button to generate a category summary, which will list all of the totals for you main donation categories, your donation subcategories, and your donation "appeal codes".

    Using this printout, a nonprofit worker can pretty easily figure out what information needs to be entered into Quickbooks to correspond to a bank deposit they make on a given day.

    Thinking in terms of workflow, this system also allows the nonprofit to do an audit of their records... for paper checks, the nonprofit will be able to make sure that the total amount deposited equals the total amount of $$ tracked in their donor database – i.e. search by ofline gifts ENTERED between a particular date range, or by online gifts MADE during the reporting period of your donation processing service (i.e. March 1 to March 31).

    I hope these comments are useful!


    1. Nov 09, 2005

      Super useful comments! For phase 1, we won't be able to address the automated solution - but you've provided some good starting points for thinking about that...

      However, we think we can provide a reasonable solution for retrieval of category-based aggregation totals in phase 1 - with some fairly minor modifications to existing spec:

      • Your Categories map well to the ContributionType data structure (e.g. there can be ContributionType instance for Donations, Membership Renewals, etc. - as many as needed).
      • We'll add an accounting_code column to ContributionType - to support mapping to Quickbooks/Other Acctg Package GL/Category codes.
      • The spec'd Contribution Search functionality supports search by Contribution Type and Date range. We'll add totaling and additional filter by Payment Instrument (which would allow you to see 'checks only' for a date range, for example).

      These additions would allow an org to print out a list and totals for contributions by date and category. And if they wanted to massage the data elsewhere or import the details to their accounting system, they could export the result sets.


  14. Nov 09, 2005

    Rich Cowan dit :

    Dave, glad to help. I should also note that I gave an incorrect link to the Beta of ODB. The correct link is:


  15. Nov 10, 2005

    JoeMurray dit :

    I'd like to support Rich on the importance of a) batch totals rather than individual contributions going into Quickbooks, and b) the presence of a human in the loop. My client's auditor highly recommends the latter.

Creative Commons License
Except where otherwise noted, content on this site is licensed under a Creative Commons Attribution-Share Alike 3.0 United States Licence.