CiviPledge - Self-service Pledges and Online Pledge Payments

This issue covers functionality need to allow constituents to make pledges via Online Contribution Pages, and submit scheduled payments for their pledges via credit / debit card.

Self-service Pledge Settings
======================
Pledges are enabled for an Online Contribution page via a new set of fields added to the existing configure "Contribution Amounts" form (CRM/Contribute/Form/Manage/Amount). NOTE: Including these settings in an existing form is preferable given that there are already 8 steps to the new contrib page wizard.)

Schema
------------
New Table = civicrm_pledge_block

• id
• entity_table
• entity_id
• pledge_frequency_unit VARCHAR(128), Delimited list of supported frequency units (same approach as contribution_page.recur_frequency_unit)
• is_pledge_interval BOOLEAN, DEFAULT 0, Is frequency interval exposed on the contribution form
• max_reminders, INT, DEFAULT 1
• initial_reminder_day, INT, DEFAULT 5
• additional_reminder_day, INT, DEFAULT 5

Configure Contribution Page - Additions to the Amount Form
----------------------------------------------------------------------------------
If CiviPledge component is enabled, the following fields are added to the form:

• Enable Pledges for this contribution page (checkbox).

If checked, unhide the following fields:

• Supported pledge frequencies [ ] day [ ] week [ ] month [ ] year (should be required field)
• Allow frequency intervals (checkbox)
• Send initial reminder [ ] days prior to scheduled payment due date
• Send up to [ ] reminders for each scheduled payment
• Send additional reminders [ ] days after the last one sent, up to the maximum number of reminders

Form Rule
==============

• "You can not enable both Recurring Contributions AND Pledges on the same online contribution page."

Make a New Pledge via Online Contrib Page
===================================
When pledges are enabled for an online contribution page, then the following radio button group is added just below the amount block:

---------------------------------------------------------------------------------------------------------
[o] I want to make a one-time contribution
[ ] I pledge to contribute this amount every [ ] [ week(s) ] for [ ] installments
---------------------------------------------------------------------------------------------------------

NOTE: The frequency_interval in the above line is included conditionally if is_pledge_interval =1. Frequency unit drop-down label suffixes switch from *ly to *(s) using the same logic as the recurring contribution fields.

If Pay Later is enabled for the contribution page, the pay_later checkbox is included - below the pledge fields - and the payment_instrument for the Pledge is set to Check.

Form Rule Notes
------------------------

• Installments field is required and must be an integer and must be > 1 (This is different from the recurring contributions rule, where # of installments are NOT required.) If user enters 1 as number of installments - give the following error msg: "Pledges consist of multiple scheduled payments. Select one-time contribution if you want to make your gift in a single payment."
• frequency_unit is required unless hidden and must be an integer
• Eligibility for Premiums are calculated on the calculated Pledge Amount (rather than the single contribution - e.g. pledge payment - amount). EXAMPLE: Minimum contribution for premium = $100. A pledge for $10 ... every [1] month for [ 12 ] installments IS eligible for the premium.
• Requirements are the same for all other contribution form fields (billing, profiles etc as configured)

PostProcess
-----------------
In all cases we will create the initial contribution record, a pledge record and one or more pledge payment records. For "pay later" the initial contribution will be "pending" as usual - as will the associated pledge_payment record.

Additions to the "normal" post process logic:
1. Insert Pledge record

• contribution_page_id = id of this page
• frequency_unit = as selected on form
• frequency_interval = as entered on form, or 1 if hidden (via settings)
• installments = as entered on the form
• max_reminders, initial_reminder_day, additional_reminder_day as set in pledge_block

To keep things simple, the following assumptions will be made when creating the Pledge record and payment schedule:

• Pledge Made (create_date) and Payments Start (start_date) both = today()
• Payments due on... (frequency_day) = 1.
• Contribution type = contribution_type_id of the contribution_page

2. Insert Pledge Payment record(s) as required by calculated payment schedule

• The first pledge payment will be linked to the contribution record we create for this session. Status will need to be updated accordingly.
• Additional pledge payment records will have status = Pending and pledge_id = this pledge.

NOTE: We probably need a BAO function which updates associated pledge_payment record when an contribution record's status is updated. This may already have been implemented for offline "record pledge payments".

Self-Service (online) Pledge Payments
==============================
Constituents will be able to make their ongoing pledge payments via the same online contribution page where they made their initial pledge. However, we will need to positively identify the pledge being paid. This can happen in two ways:

1. Contact clicks a link in their "pledge reminder email" which contains the pledge id and a temporary authentication hash. The link directs them to "their" online contribution page. Logic is added to the contribution page to verify the hash and load the pledge id into the session.

2. CMS User logs in and clicks a "Make Payment" link from the CiviCRM Contact Dashboard. Pledge ID is included in the link and loaded into the online contribution page session. In this case the hash authentication is not necessary.

Changes to Online Contribution Page (Main.php) for Self-service Payments
------------------------------------------------------------------------------------------------------
If a pledge ID is passed in the GET params AND either we have an authenticated user OR a validated hash AND pledges are enabled for the page....

• Verify that the contact "owns" the passed pledge and there are one or more Pending or Overdue payments.
• Hide the Amount block, the (new) Pledge fields, and the Pay Later field
• Instead we show display a list of the "next due" (1 only) pledge payment with checkbox. If there are any overdue payments - list those above the "next due" (next in Pending status). User can choose which to pay by checking the boxes.

Example: Pledge has one overdue payment (was due June 15), and the next (pending) payment is due on July 15
--------------------------------------------------------
Make Pledge Payment(s):
[ x ] $100 - due on June 15 (overdue)
[ ] $100 - due on July 15
--------------------------------------------------------

Defaults: All "payment rows" are checked by default
Form Rule: At least one payment row must be checked on submit.
PostProcess:

• Contribution amount = total of checked payments
• Pledge payment record(s) and pledge status are updated based on result of contribution processing
• All other processes are "as normal"

Changes to Reminder Email Feature
--------------------------------------------------
If the Pledge record has a linked contribution page (civicrm_pledge.contribution_page_id not NULL), the ReminderMessage.tpl is passed a flag telling it to include a link "Pay Online". Link directs to the online contribution page and includes the pledge id and add checksum validation.

Changes to (offline) Pledge Form
---------------------------------------------
We also can allow admin's to enable self-service payment for any pledge that was entered in the back-office by exposing a <select> field for "Self-service Payments Page" (listed options are all active online contribution page record where Pledge is enabled).

Changes to Contact Dashboard
-------------------------------------------
If Site Preferences >> Contact Dashboard setting includes "Pledges" AND the contact has one or more pledges - we show Pledge/Pledge Payments selector on the dashboard. As with other selectors on the dashboard - we exclude the contact_type icon, contact name, and all action links. The Payments link (drilldown) is retained in the 'actions' column of pledge rows.

For any Pending, In Progress or Overdue Pledge records where the contibution_page_id is NOT NULL - add a new "action" link to the Pledge rows: "Pay Online". This link goes to associated contribution page, and passes pledge ID.

NOTE: The idea is to pass the pledge ID to the online contrib page and the logic there will figure out what payments are due / overdue (as described in the section above). This seems better than requiring the user to drill down to the Payments level on the contact dashboard and select one or more payments to "Make Payment". It is also consistent with how the online contrib page is called from the reminder emails.