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 (??)

Issues:
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; civicrm_contribution_page.id 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)

Examples:

• 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 config.inc.php 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)
• PASSWORD
• CURRENCY_CODE
• CHARACTER_SET

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

ContributionType

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

PaymentInstrument

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

Contribution

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.

FinancialTrxn

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 config.inc.php)
• 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.

Requirements:

• 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 = contribute_type.name
  • module = CiviDonate
  • callback = (function to display Contribution details)
  • activity_id = PK of new Contribution record
  • activity_summary = "$method - $xxx.xx - $contribute_mode.name"
    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 = contribute_type.name + '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...).

Details: http://objectledge.org/jira/browse/CRM-496

Profile Enhancements

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

Details: http://objectledge.org/jira/browse/CRM-483