2. Payment Plan/ Instalments (Phase 1-3)



Payment Plan v6.bmpr

Phase structure of the project

0 From Recurring Contribution to Payment Plan

This specification is a plan to utilise what CiviCRM recurring contribution already provides to fulfil some of the very important use cases of payment plan such as pay in instalments. At the end of the implementation, the new changes will transform the recurring contrition to be a powerful tool to handle different ways that a user might wish to pay for an order.

As a result, we should be able to rename the recurring contribution to payment plan in the UI and introduce it to the users as a complete solution.

Phase 1 - Infrastructure and UI

1.1 Recurring Contribution Changes for Membership Payment Plan

Guidance for reading

In this section, in order to simplify the calculations in the specification we have used the example of paying for a £120 worth 1 year standard membership in 12 monthly instalments via webform.


SpecWireframes and notes

Pay later support for pay by instalments:

Currently when a recurring contribution is created with a number of instalments, only one contribution will be generated on creation. The rest contributions will be created when each interval occurs.

We need to change this to generate all contributions on recurring contribution creation.

1. If a person chose to pay for a membership in 12 instalments via "pay later" option, a recurring contribution should be created with 1/12 of the membership fee per instalment for 12 instalments.

2. All 12 contributions should be generated upon submission at once. All contributions will be in status "Pending" until being marked as "Complete" manually.

3. The linked membership will have full one year duration and will be activated upon the completion of the first contribution.

Sample webform configuration:
  1. Create a webform and enable Enable CiviCRM Processing on the CiviCRM tab section
  2. Enable First Name, Last Name and Email for the Contact 1
  3. Enable one membership for Contact 1.
  4. Enable Membership Fee on the membership tab
  5. Select a Contribution Page that has Pay Later option on the Contribution tab
  6. Select "month" in "Frequency of Instalments". Enable number of instalments and Interval of Instalments
Deal with Line items issue so invoices are generated correctly. 

1. Each contribution instead of linking to the same 1 year membership line item, it should link to its own portion of line item split in number of instalments. In the example, a line item of "Standard Membership (8.33%)" will be created for each contribution generated by the recurring contribution.

2. Each contribution will have its own invoice reflecting the amount and status of payment for its own portion line item.


Since we are generating all instalment contributions upfront, we need to make sure when any pending instalment contribution is completed, the membership duration doesn't get extended.

If a membership is linked to a recurring contribution with instalments (civicrm_contribution_recur.installments != NULL), when a contribution linking to such recurring contribution is marked as complete, the membership duration should not get extened.



1.2 Membership Status Override Improvements


SpecWireframes and notes
Improve membership status override to provide extra options to allow temporary status override.
  1. Update the "Status Override" field in the UI to have the following options: 

    Option
    No
    Override Permanently
    Override until selected date
  2. The "No" option means the membership's status is subject to membership status rules. This option is equivalent to the current "Status Override" field when unchecked.
  3. The "Override Permanently" option means the membership's will stay at the selected status and its status is NOT subject to membership status rules until "Status Override" field is changed to "No". This option is equivalent to the current "Status Override" field when checked.
  4. For the "Override until selected date" option
    1. a new field "status_override_end_date" needs to be added to civicrm_membership table
    2. when this option is selected, a datepicker linked to the "status_override_end_date" field will appear next to the "Status Override" dropdown list. It allows the admin to select a date where the status override will expire. "is_override" field will be marked as true and the selected date will be saved into "status_override_end_date" field
    3. The "Override until selected date" option means the membership's status will stay at the selected status and its is NOT subject to membership status rules. However, on the selected date, the field will automatically change to "No" thus then the membership becomes subject to membership status rules.
  5. An upgrade script needs to be created in order to add the "status_override_end_date"

Modify "Update Membership Statuses" scheduled job to also processes memberships with "Override until selected date".
  1. Change the "Update Membership Statuses" scheduled job to also scan through the memberships whose "Status Override" field is "Override until selected date". If any of the memberships' "status_override_end_date" field is today or earlier, update its "Status Override" to "No" and empty the "status_override_end_date" field.

Webform membership status override support
  1. On webform civicrm membership tab, relabel the "Membership Status" field to be "Override Status". Relabel the option "- Automatic -" to be "No".
  2. On webform civicrm membership tab, for each membership, add a "Status Override End Date" checkbox. When checked, a date field will be added to the webform to allow admin/ user to select the date that the status override will expire. This field:
    1. does not take any effect if "Override Status" field is set to "No" in the configuration or on the form
    2. the selected date should be saved into "status_override_end_date" field if a status is selected in the "Override Status" field in the configuration or on the form

1.3 Membership Offline Auto-renew 


SpecWireframes and notes
Webform membership autorenewal support

1. Add an "Auto-renew Option" field to Webform CiviCRM membership configuration with options:

  • Not offered
  • Give option
  • Required

2. When "Not offered" is selected, the webform will not alllow autorenewal.

3. When "Give option" is selected, an "Auto-renewal option" field will be added to the webform with a checkbox option "Please renew my membership automatically." If user selected this option when purchasing a membership, the membership will be set to auto-renew. 

4. When "Required" is selected, the corresponding membership created by the webform will be set to auto-renew.

5. This field is provided to every Membership enabled in Webform CiviCRM configuration tab.

Implement auto-renew for offline payment options.
  1. When an membership is selected to auto-renew and paid by "Pay Later" option:
    1. If the membership is paid in instalments, a recurring contribution with 1/12 of the membership fee per instalment for 12 instalments (installments = 12) should be created. The "auto_renew" field for that recurring contribution needs to be set to true.
    2. If the membership is not paid in instalments, a recurring contribution with full membership fee with no instalment (installments = NULL) should be created. The "auto_renew" field for that recurring contribution needs to be set to true.
  2. All contributions will be in status "Pending" until being marked as "Completed" manually.
  3. The linked membership will have full one year duration and will be activated upon the completion of the first contribution.

Scheduled job to process offline auto renewals.

  1. Add a scheduled job “Renew offline auto-renewal memberships”.
  2. When the scheduled job is run, it finds and processes any membership that meets all following conditions:
    1. whose last recurring contribution's "auto_renew" field equals to true and its payment processor is "Pay Later" (payment processor id = 0)
    2. the status of the recurring contribution is not cancelled or refunded.
  3. If the membership's last recurring contribution has no installments (installments = NULL), generate a new pending contritbution under that recurring contribution. Then extend the membership for one term.
  4. If the membership's last recurring contribution has installments (installments != NULL), use that recurring contribution as a template to create a new recurring contribution with current date and pending contributions linking to the same membership. The contribution amount and date should be based on the recurring contribution information and other contribution information (such as line items and custom fields) should be based on the last instalment contribution from the previous recurring contribution. Then extend the membership for one term.
  5. The schedule job should also provide a hook allowing extensions to modify point 2a to add ids of other payment processors that should be considered as offline payment processors along side with "Pay Later" option. 

1.4 Membership Status Rule with Payment Plan


SpecWireframes and notes
Create membership status rules that allow for changing the membership status when payments are overdue / members fall into arrears
  1. Add a trigger event "Membership is in arrears (Payment Plan)" that qualifies when:
    1. a membership is paid by recurring contribution with instalments
    2. any pending instalment contribution's received date falls to the past
  2. Add a trigger event "Membership is no longer in arrears (Payment Plan)" that qualifies when:
    1. a membership is paid by recurring contribution with instalments
    2. no pending instalment contribution in the past
  3. With the above two new trigger events, admin will be able to create a new membership status (e.g. in arrears) which
    1. memberships will be switched to when any instalment payment has been outstanding longer than expected. Admin will be able to "Start Event Adjustment" to specify how long before an instalment contribution is classfied as overdue.
    2. memberships will be released from the rule when all due instalments are fulfilled in time.


Phase 2 - UI/ UX

2.1 Admin Process for Using Payment Plan with Membership


SpecWireframes and notes
Update status override
  1. Update the status override field to refect the new options in new membership modal.

Update admin membership screens to have option to pay with payment plan.
  1. In the payment section of "New Membership" and "Renew Membership" modals, two options should be provided:
    1. Contribution
    2. Payment Plan
  2. Contribution option is the traditional way of paying for a membership which is by creating a single contribution. This option keeps the original behaviour of how it works currently in CiviCRM.
  3. Payment Plan option allows user to pay for the membership in instalments. With this option, the following fields will be provided:
    • Pay by a different contact? - allow contact other than the beneficiary to pay and also soft credit support
    • Amount - the price of the selected membership.
    • Financial Type - the financial type the recurring contribution and contribution should use
    • Number of Instalments - number of instalments the full price should be slipt into
    • Interval and interval unit - the gap between two instalments
    • Payment Method - payment method used for the instalment contibutions 
    • Payment Plan Start Date - Date of the first instalment contribution
    • Notes
  4. If a new membership is created with payment plan option as per example via the admin interface:
    • A recurring contribution will be created with total amount of £120 with 12 instalments every month starting from the "Payment Plan Start Date" user specified.
    • 12 contributions with line item "Standard Membership (8.33%)" will be generated and they will link to the membership.
    • All contributions will be "Pending"
    • The membership will have full one year duration and will be activated when a contribution linked to the membership is marked as "Completed"
  5. If a membership is renewed with payment plan option as per example via the admin interface:
    • A recurring contribution will be created with total amount of £120 with 12 instalments every month starting from the "Payment Plan Start Date" user specified.
    • 12 contributions with line item "Standard Membership (8.33%)" will be generated and they will link to the membership.
    • All contributions will be "Pending"
    • The membership will be extended for a full year.
Auto renewal option in admin screens for creating payment plan for membership only
  1. Add an "Auto-renew offline?" option on top of "Contribution and Payment Plan" section.
  2. When "Auto-renew offline?" option is checked:
    1. If the membership is going to be paid by contribution, it will create a recurring contribution with no installments (installments = NULL) and auto-renew marked as true. A contribution will be created under the recurring contribution
    2. If the membership is going to be paid by payment plan, it will create a recurring contribution with the specified number of installments and auto-renew marked as true. One contribution per instalment will be created under the recurring contribution with status "Pending".
  3. When renewing an membership that is already configured to auto-renew, the "Auto-renew offline?" option can no longer be checked. Instead, a cross mark will be shown and followed with instruction "This membership is already set up to auto-renew. You can still choose to make an addtional renewal payment below."

2.2 Payment Plan Information


SpecWireframes and notes
Change to membership modal to display payment plan related information
  1. Relabel the "Related Contributions" accordion to "Related Contributions and Payment Plans".
  2. In the accordion, it should show:
    1. a contributions section showing a table of all non-payment-plan contributions that are linked to the membership when applicable.
    2. a payment plans section showing a table of all payment plans that are linked to the membership when applicable.
  3. The contribution table in 2a should have the look and behaviour of the current contribution table in contact record's contribution tab.
  4. The payment plan table in 2b should have the following columns:
    1. Instalment Amount - the amount that each linked contribution will be generated with
    2. instalments - number of instalments. Will be empty if it is not a payment plan paid in instalments
    3. Frequency - gap between 2 contribution occurance
    4. Total Amount - amount that sums up the amount of all linked contributions
    5. Paid - total amount of all received payments against all linked contributions
    6. Due - total amount of all linked contributions whose received date is in the past/ today
    7. Balance - Total Amount - Paid. Will be empty if it is not a payment plan paid in instalments
    8. Start Date - start date of the payment plan
    9. End Date - end date of the payment plan. Will be empty if the payment plan hasn't ended.
    10. Status - status of the payment plan. Also show the next due date (the next contribution received date).
  5. A caret icon should be presented on the left end of each payment plan row to allow admin to drill down a payment plan to see all its linked contributions. The contributions should be shown in a sub-table with the look and behaviour of the current contribution table in contact record's contribution tab.
  6. A vertical ellipses should be presented on the right end of each payment plan row to allow admin to view and edit the payment plan and also add a new contribution to the payment plan.

Change to recurring contribution modal to display payment plan related information
  1. Rename the "Recurring Contributions" modal to "View Payment Plan".
  2. The following fields should be show to the modal:
    1. Contact - contact display name with link to contact record
    2. Instalment Amount - the amount that each linked contribution will be generated with
    3. instalments - number of instalments. Will be empty if it is not a payment plan paid in instalments
    4. Frequency - gap between 2 contribution occurance
    5. Total Amount - amount that sums up the amount of all linked contributions
    6. Paid - total amount of all received payments against all linked contributions
    7. Due - total amount of all linked contributions whose received date is in the past/ today
    8. Balance - Total Amount - Paid. Will be empty if it is not a payment plan paid in instalments
    9. Start Date - start date of the payment plan
    10. End Date - end date of the payment plan. Will be empty if the payment plan hasn't ended.
    11. Status - status of the payment plan.
    12. Next Contribution - show the next due date (the next contribution received date)
    13. Failure Count - count of the failure of collecting payments (unchanged - only relevant to online payments)
    14. Failure Retry Date - the next date to retry the payment collection (unchanged - only relevant to online payments)
    15. Payment Processor - which payment processor is used to collect payment. Show "Pay Later" when payment_procesorr_id = 0
    16. Financial Type
    17. Payment Method
  3. A "Contribution" Accordion should be added to the bottom of the "View Payment Plan" modal. It should show a table listing all contributions that are linked to this payment plan. The table should have the look and behaviour of the current contribution table in contact record's contribution tab.
Extract payment plans onto its own contact page tab.
  1. Create two subtabs under the contact contribution tab: Contributions and Payment Plans.
  2. The Contributions subtab shows all non-payment-plan contributions in the view that currently exist in contact contribution tab.
  3. The Payment Plans subtab will show two sections:
    1. Active Payment Plans: a table showing all payment plans that are currently pending or in progress.
    2. Inactive Payment Plans: a table showing all payment plans that are completed or cancelled.
  4. The payment plan tables should reuse the table structure and behaviour from the payment plan table in view membership modal.

Phase 3 - Payment Plan Management

3.1 Operations on existing payment plans


Spec

Update payment plan
  1. Make "Number of instalment" field readonly if the recurring contribution is using a payment processor with "Payment_Manual" class.
  2. Expose the "Auto Renew?" field on "Update Recurring Contribution" form.
  3. Expose "Payment Method" field, "Cycle Day" field on "Update Recurring Contribution" form.
  4. When admin click on save on "Update Recurring Contribution" form, if "Payment Mehod" or "Cycle Day" is changed, a popup should appear asking "Do you want to update any outstanding instalment contribution with the new Payment Method/ Cycle Day?".
  5. If admin chose "No" in the previous popup. No existing contribution will get affected.
  6. If admin chose "Yes" in the previous popup. Any existing Pending contribution under the recurring contribution will reflect the new "Payment Method" and "Cycle Day".

Cancel existing payment plan
  1. When cancelling a recurring contribution, a popup will show up and ask for confirmation. A new dialog box containing two checkbox options should be used to replace the popup.
  2. The first checkbox is "Do you wish to cancel any pending instalment contribution?" which if checked and confirmed, as a result, all "Pending" contributions that are linked to the recurring contribution will also be cancelled.
  3. The second checkbox is "Do you wish to cancel any linked membership?" which if checked and confirmed, as a result, all memberships that are linked to the recurring contribution will also be cancelled.

3.2 Membership price update




Update membership fee when offline auto-renew
  1. Add a "Payment Plan Settings" to Administer menu.
  2. In the settings page, a configuration checkbox "Use latest price when auto renew membership?" should be provided.
  3. If the "Use latest price when auto renew membership?" is not checked, nothing changes.
  4. If the "Use latest price when auto renew membership?" is checked, when an offline auto renew membership is being renewed by the "Renew offline auto-renewal memberships" scheduled job
    1. the generated contribution/ recurring contribution should reflect the current membership fee configured in the corresponding membership type for each membership line included in the recurring contribution
    2. the line items and other sub-entities of the generated contributions should also reflect the current membership fee configured in the corresponding membership type

Offline auto-renew option
  1. Add a "Offline auto-renew option" custom fieldset to Membership Entity with boolean custom field "Opt-out auto price update for offline auto-renew".
  2. When"Opt-out auto price update for offline auto-renew" is true for a membership, if "Use latest price when auto renew membership?" is turned on, this membership should not reflect the new price when it gets auto-renewed by the offline auto-renew scheduled job.

3.3 Instalment management (WIP)

Wireframes 



Offline Recurring Contribution Line Item Table
  1. Create a database table "membershipextras_subscription_line" upon installation of the extension. The database table have following columns:
    1. contribution_recur_id - integer - required
    2. line_item_id - integer - required
    3. start_date - date
    4. end_date - date
    5. auto_renew - boolean
    6. is_removed - boolean

Create Line Item for Offline Recurring Contribution and create reference
  1. Adding a hook or adding into an existing hook so that when a recurring contribution is created using an offline payment processor (payment processor with Payment Manual class):
    1. create a copy of each line item of a instalment contribution
    2. the contribution_id of the copied line items should NULL
    3. a record should be created in "membershipextras_subscription_line" table for each of the copied line item:
      1. contribution_recur_id - the id of the recurring contribution
      2. line_item_id - the id of the copied line item
      3. start_date - start date of the recurring contribution
      4. end_date - leave empty
      5. auto_renew - true if the recurring contribution auto-renews, otherwise false
      6. is_removed - false

Payment plan period links
  1. Creating a custom fieldset "Related Payment Plan Periods" for recurring contribution entity. It should contain two read-only integer fields:
    1. Previous Payment Plan Period
    2. Next Payment Plan Period

View/Modify Future Instalments action - current period
  1. Add a "View/Modify Future Instalments" action to any recurring contribution that uses an offline payment processor (payment processor with payment manual class).
  2. When the action is selected, a "Manage Instalments" modal popup should appear.
  3. In the current period tab (default), each "membershipextras_subscription_line" whose start date is not empty and is_removed = false should be displayed. each row should have the following information:
    1. Item - line item label
    2. Start date - start_date in membershipextras_subscription_line
    3. End date - biggest end date among all linked memberships
    4. Renew automatically - auto_renew in membershipextras_subscription_line. This should not show if the recurring contribution is not auto-renew.
    5. Financial type - financial type of the line item
    6. Tax - the tax percentage of the financial type, show N/A if there is no tax account in the financial type
    7. Amount - line total of the line item
    8. Remove button - show as bin icon
  4. An "Add Membership" button and an "Add Other Amount" button should be shown under the last row
  5. At the bottom of the tab, the following information should be shown:
    1. Untaxed Amount - total amount of the line_totals
    2. Tax - total amount of tax_amounts
    3. Total per instalment - sum of a and b

View/Modify Future Instalments action - next period
  1. In the "Manage Instalments" modal popup, a next period tab should be shown if the recurring contribution has auto-renew enabled and it has at least one membership.
  2. In the next period tab (default), each "membershipextras_subscription_line" with auto-renew = TRUE should be displayed. each row should have the following information:
    1. Item - line item label
    2. Financial type - financial type of the line item
    3. Tax - the tax percentage of the financial type, show N/A if there is no tax account in the financial type
    4. Amount - line total of the line item
    5. Remove button - show as bin icon
  3. An "Add Membership" button and an "Add Other Amount" button should be shown under the last row
  4. At the bottom of the tab, the following information should be shown:
    1. Untaxed Amount - total amount of the line_totals
    2. Tax - total amount of tax_amounts
    3. Total per instalment - sum of a and b
Remove a line from a standard multi-line membership order
  1. In the "View/Modify Future Instalments" current period tab, user can click on the bin button on each of the line item to perform a removal action.
  2. Once the bin button is clicked, if the item is the last item in the current period tab, a notice with warning sign should appear with text "Cannot remove the last item in an order" and action should be cancelled.
  3. Once the bin button is clicked, if the item is not the last item in the current period tab, a dialog with title "Remove LINE_ITEM_LABEL ?" should appear with the following components:
    1. dialog body text - "LINE_ITEM_LABEL amount should be deducted from all remaining instalments after the end date. Please note the changes should take effect immediately after "Apply"."
    2. Adjust end date - checkbox option
    3. End date - datepicker that should only be shown if "Adjust end date" is checked, default to today's date
    4. Cancel button
    5. Apply button
  4. If user clicked on "Apply":
    1. end_date in membershipextras_subscription_line for the corresponding item should be filled in with today's date. If "Adjust end date" is checked, the end_date should be set to the date user picked.
    2. auto_renew in membershipextras_subscription_line for the corresponding item should set to False.
    3. is_removed in membershipextras_subscription_line for the corresponding item should set to True.
    4. for any "Pending" instalment contribution with "Received Date" equals to or after the end_date, any line_item with same label as the recurring line item should be removed. Contribution amounts should be adjusted.
    5. if the line item is a membership, update the corresponding membership (linked to the recurring contribution) to have the new end_date and clear the contribution_recurr_id
    6. a notice should appear with text "LINE_ITEM_LABEL has been removed from the active order."
    7. a notice should appear with text "LINE_ITEM_LABEL should no longer be continued in the next period."
    8. the content of "Manage Instalments" modal should be reloaded.
  5. If user clicked on "Cancel", the action should be cancelled and no change is made.

Remove a line from a standard multi-line membership order - next period only
  1. In the "View/Modify Future Instalments" next period tab, user can click on the bin button on each of the line item to perform a removal action.
  2. Once the bin button is clicked, a dialog with title "Remove LINE_ITEM_LABEL ?" should appear with the following components:
    1. dialog body text - "Please note the changes should take effect immediately after "Apply"."
    2. Cancel button
    3. Apply button
  3. If user clicked on "Apply":
    1. auto_renew in membershipextras_subscription_line for the corresponding item should set to False.
    2. is_removed in membershipextras_subscription_line for the corresponding item should set to True.
    3. if the line item is a membership, clear the contribution_recurr_id of the corresponding membership (linked to the recurring contribution)
    4. a notice should appear with text "LINE_ITEM_LABEL should no longer be continued in the next period."
    5. the content of "Manage Instalments" modal should be reloaded.
  4. If user clicked on "Cancel", the action should be cancelled and no change is made.
  5. User can also uncheck "Renew automatically" field for any of the line in "Current period" tab to perform the same action. Point 2-4 also apply here.
Add a membership line to a standard multi-line membership order
  1. In the "View/Modify Future Instalments" current period tab, user can use "Add Membership" and "Add Other Amount" buttons to add line items to the current order.
  2. Once the "Add Membership" is clicked, a new row should appear in current period tab with the following information:
    1. Item - required - a dropdown contains all membership types which are not belong to any of the membership organisation for the existing lines
    2. Start date - required - a datepicker default to today's date. If there is an active membership of the same type, default to the start date of that membership.
    3. End date - required - a date picker default to biggest end date among all linked memberships
    4. Renew automatically - a checkbox checked by default, only show if the recurring contribution has auto-renew enabled.
    5. Financial type - text showing the financial type of the selected membership
    6. Tax - text showing the tax percentage of the financial type, show N/A if there is no tax account in the financial type
    7. Amount - required - a money input box defaulted to the minimum_fee of the membership type divided by number_of_instalments.
    8. cross icon - cancel action
    9. check icon - confirm action
  3. When a row is added but not yet confirmed/ cancelled, any parts of the modal popup other then the row itself should be made unclickable. If the user tries to click on any other parts, the row should flash to remind the user an item is yet to be completed.
  4. If user clicked on cross icon, the row should be cancelled and no change is made.
  5. When user clicked on the check icon, if there is no "Pending" instalment contribution with "Received Date" equals to or after the today/ start date (whichever is later), a notice with warning sign should appear with text "No outstanding instalment contribution from the selected start date. Suggest to follow the steps below:
    1. Add the the item to next period instead.
    2. (optional) Create the membership or contribution outside the reucrring order."
  6.  When user clicked on the check icon, if there are "Pending" instalment contributions with "Received Date" equals to or after the today/ start date (whichever is later), a dialog with title "Add LINE_ITEM_LABEL ?" should appear with the following components:
    1. dialog body text - "Please note the changes should take effect immediately after "Apply"."
    2. a "Adjust the amount of the first instalment" checkbox option.
    3. a "First instalment amount" money text input. Defaults to the instalment amount. This is only revealed when "Adjust the amount of the first instalment" checkbox is ticked.
    4. Cancel button
    5. Apply button
  7. If user click on "Apply" button:
    1. a line item with empty contribution_id should be created according to the information user inputted. Note that the tax_amount will calculated by multiplying amount with tax rate.
    2. membershipextras_subscription_line should be created linking the line item and the recurring contribution. It's start date should be the selected start date and it's end date should be empty.
    3. for any "Pending" instalment contribution with "Received Date" equals to or after the today/ start date (whichever is later), a copy of the line_item should be added. Contribution amounts should be adjusted. If "Adjust the amount of the first instalment" is checked, the first  "Pending" instalment contribution should apply "First instalment amount".
    4. if a membership of the same type doesn't yet exist, a new membership should be created with the start date and end date and linked to all "Pending" instalment contribution with "Received Date" equals to or after the today/ start date (whichever is later).
    5. if a membership of the same type already exists, it should be updated with the new start date and end date and linked to all "Pending" instalment contribution with "Received Date" equals to or after the today/ start date (whichever is later).
    6. if auto_renew is checked, the auto_renew in membershipextras_subscription_line for the corresponding item should set to TRUE. The membership contribution_recurr_id should be set to the id of the recurring contribution.
    7. if auto_renew is not checked, the auto_renew in membershipextras_subscription_line for the corresponding item should set to FALSE. The membership contribution_recurr_id should be emptied.
    8. a notice should appear with text "LINE_ITEM_LABEL has been added to the active order."
    9. if auto-renew is selected, a notice should appear with text "LINE_ITEM_LABEL will now be continued in the next period."
    10. the content of "Manage Instalments" modal should be reloaded.
  8. If user clicked on "Cancel", the action should be cancelled and no change is made.

Add an other amount line to a standard multi-line membership order
  1. In the "View/Modify Future Instalments" current period tab, user can use "Add Membership" and "Add Other Amount" buttons to add line items to the current order.
  2. Once the "Add Other Amount" is clicked, a new row should appear in current period tab with the following information:
    1. Item - required - a text box
    2. Start date - required - a datepicker default to today's date.
    3. End date - text "N/A"
    4. Renew automatically - a checkbox checked by default, only show if the recurring contribution has auto-renew enabled.
    5. Financial type - select list with all available financial types
    6. Tax - text showing the tax percentage of the selected financial type, show N/A if there is no tax account in the selected financial type
    7. Amount - required - a money input box
    8. cross icon - cancel action
    9. check icon - confirm action
  3. When a row is added but not yet confirmed/ cancelled, any parts of the modal popup other then the row itself should be made unclickable. If the user tries to click on any other parts, the row should flash to remind the user an item is yet to be completed.
  4. If user clicked on cross icon, the row should be cancelled and no change is made.
  5. When user clicked on the check icon, if there is no "Pending" instalment contribution with "Received Date" equals to or after the today/ start date (whichever is later), a notice with warning sign should appear with text "There are no instalments left for this period. Suggest to follow the steps below:
    1. Add the the item to the next period.
    2. (optional) Create the membership or a one-off contribution outside the recurring order."
  6.  When user clicked on the check icon, if there are "Pending" instalment contributions with "Received Date" equals to or after the today/ start date (whichever is later), a dialog with title "Add LINE_ITEM_LABEL ?" should appear with the following components:
    1. dialog body text - "Please note the changes should take effect immediately after "Apply"."
    2. a "Adjust the amount of the first instalment" checkbox option.
    3. a "First instalment amount" money text input. Defaults to the instalment amount. This is only revealed when "Adjust the amount of the first instalment" checkbox is ticked.
    4. Cancel button
    5. Apply button
  7. If user click on "Apply" button:
    1. a line item with empty contribution_id should be created according to the information user inputted. Note that the tax_amount will calculated by multiplying amount with tax rate.
    2. membershipextras_subscription_line should be created linking the line item and the recurring contribution. It's start date should be the selected start date and it's end date should be empty.
    3. for any "Pending" instalment contribution with "Received Date" equals to or after the today/ start date (whichever is later), a copy of the line_item should be added. Contribution amounts should be adjusted. If "Adjust the amount of the first instalment" is checked, the first  "Pending" instalment contribution should apply "First instalment amount".
    4. if auto_renew is checked, the auto_renew in membershipextras_subscription_line for the corresponding item should set to TRUE. Otherwise FALSE.
    5. a notice should appear with text "LINE_ITEM_LABEL has been added to the active order."
    6. if auto-renew is selected, a notice should appear with text "LINE_ITEM_LABEL will now be continued in the next period."
    7. the content of "Manage Instalments" modal should be reloaded.
  8. If user clicked on "Cancel", the action should be cancelled and no change is made.

Add a membership line to a standard multi-line membership order - next period only
  1. In the "View/Modify Future Instalments" next period tab, user can use "Add Membership" and "Add Other Amount" buttons to add line items to the current order.
  2. Once the "Add Membership" is clicked, a new row should appear in next period tab with the following information:
    1. Item - required - a dropdown contains all membership types which are not belong to any of the membership organisation for the existing lines
    2. Financial type - text showing the financial type of the selected membership
    3. Tax - text showing the tax percentage of the financial type, show N/A if there is no tax account in the financial type
    4. Amount - required - a money input box defaulted to the minimum_fee of the membership type divided by number_of_instalments.
    5. cross icon - cancel action
    6. check icon - confirm action
  3. When a row is added but not yet confirmed/ cancelled, any parts of the modal popup other then the row itself should be made unclickable. If the user tries to click on any other parts, the row should flash to remind the user an item is yet to be completed.
  4. If user clicked on cross icon, the row should be cancelled and no change is made.
  5. When user clicked on the check icon, a dialog with title "Add LINE_ITEM_LABEL ?" should appear with the following components:
    1. dialog body text - "Please note the changes should take effect immediately after "Apply"."
    2. Cancel button
    3. Apply button
  6. If user click on "Apply" button:
    1. a line item with empty contribution_id should be created according to the information user inputted. Note that the tax_amount will calculated by multiplying amount with tax rate.
    2. membershipextras_subscription_line should be created linking the line item and the recurring contribution. It's start date and end date should be empty.
    3. a notice should appear with text "LINE_ITEM_LABEL will now be continued in the next period."
    4. the content of "Manage Instalments" modal should be reloaded.
  7. If user clicked on "Cancel", the action should be cancelled and no change is made.
  8. User can also check "Renew automatically" field for any of membership lines in "Current period" tab to perform the same action. A notice with warning sign will appear with text "This membership type is already enrolled in next period." when there is another membershipextras_subscription_line:
    1. linked to a line item with same membership type and membershipextras_subscription_line
    2. end date is empty
    3. auto-renew is TRUE
  9. If user checks the "Renew automatically" field for any of membership lines in "Current period" tab and the scenario in point 8 does not apply, point 5-7 should apply here.
Add an other amount line to a standard multi-line membership order - next period only
  1. In the "View/Modify Future Instalments" next period tab, user can use "Add Membership" and "Add Other Amount" buttons to add line items to the current order.
  2. Once the "Add Other Amount" is clicked, a new row should appear in next period tab with the following information:
    1. Item - required - a text box
    2. Financial type - select list with all available financial types
    3. Tax - text showing the tax percentage of the selected financial type, show N/A if there is no tax account in the selected financial type
    4. Amount - required - a money input box
    5. cross icon - cancel action
    6. check icon - confirm action
  3. When a row is added but not yet confirmed/ cancelled, any parts of the modal popup other then the row itself should be made unclickable. If the user tries to click on any other parts, the row should flash to remind the user an item is yet to be completed.
  4. If user clicked on cross icon, the row should be cancelled and no change is made.
  5. When user clicked on the check icon, a dialog with title "Add LINE_ITEM_LABEL ?" should appear with the following components:
    1. dialog body text - "Please note the changes should take effect immediately after "Apply"."
    2. Cancel button
    3. Apply button
  6. If user click on "Apply" button:
    1. a line item with empty contribution_id should be created according to the information user inputted. Note that the tax_amount will calculated by multiplying amount with tax rate.
    2. membershipextras_subscription_line should be created linking the line item and the recurring contribution. It's start date and end date should be empty.
    3. a notice should appear with text "LINE_ITEM_LABEL will now be continued in the next period."
    4. the content of "Manage Instalments" modal should be reloaded.
  7. If user clicked on "Cancel", the action should be cancelled and no change is made.
  8. User can also check "Renew automatically" field for any of other amount lines in "Current period" tab to perform the same action. Point 5-7 also apply here.
Set subscription line end date
  1. When a payment plan is marked as completed, all lines that meet the below conditions should have their end date set to the payment plan end date:
    1. start date is not empty
    2. end date is empty

Upgrader

Part 1:

  1. As a part of phase 3 upgrader, the extension should find all pre-existing offline payment plans and populate the "Offline Recurring Contribution Line Item" information for them.
  2. For each pre-existing recurring contribution using an offline payment processor (payment processor with Payment Manual class):
    1. create a copy of each line item of the last instalment contribution
    2. the contribution_id of the copied line items should NULL
    3. a record should be created in "membershipextras_subscription_line" table for each of the copied line item:
      1. contribution_recur_id - the id of the recurring contribution
      2. line_item_id - the id of the copied line item
      3. start_date - start date of the recurring contribution
      4. end_date - end date of the recurring contribution. If empty, leave empty.
      5. auto_renew - true if the recurring contribution auto-renews, otherwise false
      6. is_removed - False

Part 2:

  1. As a part of phase 3 upgrader, the extension should find all pre-existing payment plans that meet the criteria below and populate the "Related Payment Plan Periods" for them.
    1. payment plan that uses an offline payment processor (payment processor with Payment Manual class)
    2. payment plan whose number of instalment is larger than 0
    3. payment plan whose end date is not empty and is more a month earlier than toady
    4. payment plans whose auto-renew is set to True
    5. the contact has more than one payment plans that meet criteria a, b and c
  2. Find all memberships that are linked to payment plan that meets the criteria. Fill in the  "Previous Payment Plan Period" and "Next Payment Plan Period" with number 0.
  3. This needs to be part of the installer too.

(ON HOLD) Part 3:

  1. As a part of phase 3 upgrader, the extension should find all pre-existing payment plans that meet the criteria below and populate the "Related Payment Plan Periods" for them.
    1. any payment plans that use an offline payment processor (payment processor with Payment Manual class)
    2. any payment plan whose number of instalment is larger than 0
    3. any payment plans whose auto-renew is set to True
    4. the contact has more than one payment plans that meet criteria a, b and c
  2. Find all memberships that are linked to payment plan that meets the criteria. If two payment plans are linked to the same membership, fill in the "Previous Payment Plan Period" and "Next Payment Plan Period" with the ID of the payment plans according to payment plan start dates.

Note: we probably don't need to populate any records on installation of the extension since there should not be any offline payment plans without using the extension. If there is, it is probably not created by our extension, so it is probably safe to not populate records for them.


Auto-renew adjustment for payment plans with instalments
  1. When "Renew offline auto-renewal memberships" scheduled job is run, it finds and processes any recurring contribution that meets all following conditions:
    1. it is using an offline payment processor (payment manual class)

    2. has an end date
    3. it is set to auto-renew

    4. it is not in status cancelled

    5. number of instalments is not 0 or null
    6. it's "Next Payment Plan Period" is empty
    7. has any linked membership that meets the following conditions:

      1. end date is equal to or smaller than today

      2. the membership's type matches with any "membershipextras_subscription_line" that is auto-renew and not is_removed
  2. if the job finds any payment plan that meets the conditions in point 1:
    1. a new recurring contribution should be created using the existing recurring contribution as a template (unchanged from phase 2)
      1. The "Next Payment Plan Period" of the template recurring contribution should be filled with the id of the new recurring contribution
      2. The "Previous Payment Plan Period" of the new recurring contribution should be filled with the id of the template recurring contribution
    2. for each membershipextras_subscription_line which is auto-renew and not is_removed in the template recurring contribution:
      1. make a copy of the linked line item and link it to the new recurring contribution
      2. make a copy of the membershipextras_subscription_line and link it to the new recurring contribution. The copied membershipextras_subscription_line should have same start date as the recurring contribution and empty end date.
    3. use the last instalment as a template to create the instalments for the new recurring contribution:
      1. All information excepts the amount fields and line items should be generated the same way they are being generated in phase 2
      2. Each instalments should contain a copy of the auto-renew line items linked to the membershipextras_subscription_line
      3. the amount fields should reflect the actual amount based on the line items
    4. for each membership line items:
      1. if the user already have a membership with same type, extend that membership for a term
      2. if the user do not have any membership with same type, a new membership need to be created with start date of the recurring contribution start date.

Auto-renew adjustment for payment plans without instalments
  1. When "Renew offline auto-renewal memberships" scheduled job is run, it finds and processes any recurring contribution that meets all following conditions:
    1. it is using an offline payment processor (payment manual class)

    2. has an end date
    3. it is set to auto-renew

    4. it is not in status cancelled

    5. number of instalments is 0 or null
    6. has any linked membership that meets the following conditions:

      1. end date is equal to or smaller than today

      2. the membership's type matches with any "membershipextras_subscription_line" that is auto-renew and not is_removed
  2. if the job finds any payment plan that meets the conditions in point 1:
    1. for each membershipextras_subscription_line which is auto-renew and not is_removed in the recurring contribution: 
      1. make a copy of the linked line item and link it to the recurring contribution
      2. make a copy of the membershipextras_subscription_line and link it to the recurring contribution. The start date of the copied membershipextras_subscription_line should be the received date of the last instalment plus one interval. the end date should be empty.
      3. the end date of the original membershipextras_subscription_line should be 1 day earlier than the new membershipextras_subscription_line's start date.
    2. use the last instalment as a template to create a new pending instalment contribution under the same recurring contribution:
      1. All information excepts the amount fields and line items should be generated the same way they are being generated in phase 2
      2. Each instalments should contain a copy of the auto-renew line items linked to the membershipextras_subscription_line
      3. the amount fields should reflect the actual amount based on the line items
    3. for each membership line items:
      1. if the user already have a membership with same type, extend that membership for a term
      2. if the user do not have any membership with same type, a new membership need to be created with start date of the recurring contribution start date.

Price auto-updateIn the auto-renew process, if price auto-update is turned on and a membership is not opt-out of the price auto-update, the new/ copied line item for the membership should reflect the latest minimum membership price configured in the membership type.

3.4 Webform add-on support  (WIP)

Webform CiviCRM Integration - Membership rules improvements




Logic for pro-rate price of membership field
  1. If the 'membership fee' field is enabled, then this is the price that should be pro-rated based on the start date of the membership, the number of days in a regular period and the number of days in the pro-rated period.
  2. If the 'membership fee' field is not enabled, then the pro-rated calculation should be done based on the membership fee pulling from CiviCRM.

Calculation:

Pro-rated membership fee = (regular membership fee/ number of days in regular membership period) x number of days in pro-rated membership period

Logic for "Payment Installments" field
  1. Pay in 1 instalment
  2. Create a new recurring contribution
  3. Add to future installments of relative membership type

3) Add to future installments of relative membership type

(Compucorp custom in membership extra's extention)

Add lines to recuring contribution template invoice
If no future contributions in existing membership plan then create a single contribution to be paid immediately.
Otherwise add lines to each available future contribution