Skip to end of metadata
Go to start of metadata

This initiative will enhance CiviCRM to allow users to make payments that are for part of an invoiced amount, or for all of the amounts on several invoices using a single cheque or credit card or other payment instrument.

User Interface

This section currently presents ideas for a UI that supports these features, in the form of these annotations, which should be refined based on feedback and then used as the basis for an implementation spec.

Configurable options

Since we're concerned about some of this being overly complex for some organizations, we should consider the value of letting some of this be enabled/disabled per site. (Default OFF? Default ON?)


Partial initial payments

When submitting a contribution, the user can – if he wishes and if the contribution is configured to allow it – pay only a portion of the total amount.  This section examines how to configure the contribution/event to allow partial payment, and then how the end user can submit a partial payment.  This involves minor changes to forms that already exist in current CiviCRM versions.

Configuring a contribution page (or event)

This annotation shows changes to the "Contribution Amounts" settings tab in the contribution configuration form.  Equivalent changes should be made in the "Fees" tab of the event configuration form.

(editable here:

In a public contribution page (or event registration page)

This annotation describes changes to a public-facing contribution page. Equivalent changes should be made to public-facing event registration forms.

(editable here:

In the back-end

Besides the membership and event-registration records that an end-user creates for herself, we also need to support partial initial payments when staff users create these records in the back-end.  This is (technically) already possible in current CiviCRM versions, but we need a few improvements to make it function nicely.

New Event Registration
  • 4.1 supports an initial payment of less than the total when creating the Event Registration, but doesn't support subsequent payments.
  • On edit, we should not hide the "record a payment" controls, as long as the total of payments for the registration is less than the total registration amount.
  • NOTE: this could have implications for Participant status, if we want to, say, allow an event configuration option for "status for partially paid registrations". Do we need to add a "Partially paid" status option?
New Membership
  • 4.1 supports an initial payment of less than the total when creating the Membership, but doesn't support subsequent payments.
  • On edit, we should not hide the "record a payment" controls, as long as the total of payments for the registration is less than the total registration amount.
  • NOTE: this could have implications for Membership status, if we want to, say, allow a membership configuration option for "status for partially paid memberships."  Do we need to add a "Partially paid" status option?
New Contribution with partial initial payment

Many contributions are simply outright donations without any premium or other complexities; in this case, we don't see a need to support an initial payment of less than a total amount.  But when a contribution incorporates a complex price set, it's conceivable that we may want to record the entire contribution (with entitlements to premium gifts or other associated details) without receiving the entire amount of the contribution. In this case we need to support partial initial payments.

(editable here:


In the above form, the staff user is able to specify how the initial payment should be applied to multiple items selected from a price set.  This is done via two options:

  • Example: selected items are A: $50, B: $30, C: $20, (total of $100), and the initial payment is $50
  • Option 1: Distribute the initial payment proportionally among all selected items:
    Initial payment is 50% of the total, so each item is paid at 50%: A: $25, B: $15, C: $10
  • Option 2: Select certain items for full or partial payment:
    This option allows the user to select any number of items for full or partial payment.
Here's a sketch of how these form controls would be laid out:

Edit an existing contribution

When a staff user clicks to edit a contribution, they may want to modify the 'order' or adjust payment information. The following mockup shows a contribution entered with a price set, that has had two payments made and is having a third payment made.

Here is a mockup for editing a quick config contribution:

Edit Payment

In both quick config and price set edit contribution forms, there are links to edit existing payments. Here is a mockup of that functionality for price sets. In this case, a cheque has been received that was pending, but the amount was $40.00 instead of the expected $50.

Subsequent payments against partially paid obligations

Current versions already support creating a new contribution and recording the full payment for it.  But we also need to support recording a payment as remittance for an existing partially-paid contribution.  This section proposes UI changes to support this capability for both end-users/constituents and staff/back-office users.

Staff recording payments against a contact's partially paid obligations

"New/Edit Contribution" form:

Needs work

We should probably remove this, as parts of it are redundant with changes to the "New/Edit Contribution" form above; we should probably move some of this functionality to a "New Payment" form.


(Editable here:

End-user submitting payments against his own partially paid obligations

End-users should also be able to submit additional payments on their own outstanding obligations.  This means they'll need to see a list of all their unpaid obligations, and then be able to submit a single payment against one or all of them.

  • New form: "Submit payment for partially paid items"
    • This is very similar to a Contribution page in its layout. However, instead of configured price-set or donation amount options, this form displays a table of all unpaid obligations, similar in form and function to the "Existing obligations" section in the modified back-office "New Contribution" form described above.
    • This form is accessed through user dashboard – see the next item below.
  • New section in user dashboard: "Your partial payments".
    • This section shows a list of all contributions (memberships, event registrations, outright donations) that are "unpaid obligations": those whose total payment amount is less than the total contribution amount.
    • Each item includes a "pay now" link to a contribution form, leading to the "Submit payment for partially paid items" form (see above), with this item pre-selected.
    • This section also includes a link labeled "Pay multiple items", leading to the same form, with no items pre-selected.

Other pages and forms

Contact's "Contributions" tab

(Editable here:

Technical specification

Calculating paid amount of items in initial payment

The UI captures the user's intent regarding payment of items within the contribution (of which there is always at least one). The UI should make these calculations based on user input:

  1. Consider the initial payment as less than the total amount if both of these are true:
    1. The checkbox labeled "I'd like to pay part of this amount later" or "Record smaller initial payment" is checked.
    2. The given amount of the initial payment is less than the total contribution amount.
  2. If there's a smaller initial payment, determine the amount of that payment to apply to each item, as follows:
    1. If the user has selected "Apply to the items that I specify" (which is not available in all interfaces), calculate the paid amount of each item as follows:
      1. Items marked "pay full" are to be paid at 100% of their value.
      2. Add the value of all items marked "pay full", and subtract this sum from the total payment amount. This difference is the paid amount for the item marked "pay partial" (there should only be one item marked "pay partial").
      3. Any items not marked "pay partial" or "pay full" have a paid amount of 0.
    2. Otherwise, calculate the percentage of the total which is represented by the initial payment.  Calculate the paid amount of each item by multiplying the value of the item by this percentage.
  • None
  1. Feb 24, 2012

    After a user submits the page after choosing "partial payment", and makes no initial payment  what would a back-office user see on that contact's record?  What would be different on the contact's pledge tab and/or contact tab?  How could the bookkeeper figure out what the person still owed?

    Also, how would this work for an event registration where multiple people are being registered as part of a single transaction?

    Would this work in the case where the Event/Contribution Page used a priceset and/or offered memberships?

    Also, could the end-user specify a planned schedule of when they intend to make future payments? ( eg such as the end-user can do today when using a CiviContribute page to make a pledge or recurring contribution.)

    1. Feb 28, 2012

      1. "After a user submits the page after choosing 'partial payment', and makes no initial payment":
        1. Back-office staff can see the contribution in the Contributions tab, with a status of "Unpaid". After part of the amount has been paid, the status is "Partially Paid."
        2. Contact Summary tab and Contact Pledges tab: I don't foresee these tabs needing any changes related to partial payments or flexible payments.
        3. Figuring out what the person still owes: The Contributions tab should display a "Total amount yet unpaid", if any.
        4. I've added annotations for the Contributions tab to the wiki page above.
      2. "... for an event registration where multiple people are being registered ...":
        1. As in 4.1, the Contribution is only recorded for one contact. So the number of people on the registration should not affect the handling of flexible payments or partial payments for this contribution.
      3. "Will this work in the case where the Event/Contribution Page used a priceset and/or offered memberships?"
        1. Yes. Regarding price sets, all contribution pages and events will be using price sets (even the simplest pricing configuration is recorded as a price set in the schema). Regarding memberships, if you're wondering about how CiviCRM handles status for partially paid memberships, I suggest we may want to discuss some configuration options for that (see "New Event Registration" and "New Membership" under this section above:, but that's reaching the edge of the scope of this particular wiki page.
      4. "Could the end-user specify a planned schedule of when they intend to make future payments?"
        1. I don't believe that's within the scope of the current project.  Maybe someone will correct me on that.
  2. Feb 27, 2012



    I've just focussed on the Event / Contribution page for now. The example you've used is an onsite-payment processor. Recent discussions have highlighted how poorly the existing pay-later check box works for off-site payment processors with the discussion focussed on moving the checkbox closer to the 'continue' button (possibly even having a choice of pay-by-credit card & pay by cheque button). People tend to not click pay-later & get confused when they wind up at a credit card screen. (we get about 15% error on this).

    I think that in order to work with both types there needs to be an 'amount to pay now by credit card' field rather than an 'amount to pay later'. Depending on the mimumum  the field may or may not be editable. (& would need the minimum marked in some way). Jquery could work off that field to hide / show the credit details & potentially change the continue button to say 'continue to credit card payment'. For Pay later it would possibly make sense to have the amount box closer to the continue button


    1. Feb 28, 2012

      It's a good point, Eileen. I'll probably leave the above annotations as-are for the moment, but should find a way to implement what you're describing before moving to a next round of revisions. Thanks!

      1. Mar 07, 2012

        Thanks, Eileen. We'll implement the way you suggest, and coordinate with Dave G on shifting Pay Later to nearer Continue.

        1. Mar 12, 2012

          I've updated the annotations above to reflect this as much as possible for now. 

  3. Feb 29, 2012

    Question about the screen print for "Contact's "Contributions" tab. Instead of having to click the "view" or "edit" links to see the completed payments, would make more sense to offer a JQuery triangle icon that can be clicked to expand the contribution details. That way this is consistent with the UI on the pledge tab.

    1. Mar 12, 2012

      Agreed. I've updated the annotation. Thanks!

  4. Mar 06, 2012

    Some questions that may not belong on this wiki page, but this seems to be the best place to write them at the moment:

    1) Can flexible  payments be applied to pledge payments? And to automated credit card scheduled where on of the scheduled transactions had failed?     

    For example, a member could send in a single check of $2000, with the intent of paying off part of a membership, part of an event fee, part of a pledge payment, and also a portion to cover a gap in a scheduled sequence of automated credit card payment that had failed.     When a person writes a check to the organization, they will have no knowledge of these various CiviCRM objects. They simply expect the bookkeeper to post the check according to their instructions.

    2) When someone is not paying the full amount upfront, where would the due dates/scheduling/number installments be stored?  Someone may want to pay the remaining amount owed in 12 monthly payments, quarterly payments, or some other schedule.    The dates of when payments are expected are absolutely critical for creating an aging report, or a projected income report.   The bookkeeper will need to know if someone is 90 days overdue, 60 days overdue, etc.   The bookkeeper will also need to do cash flow projections for future dates, based on the planned schedules. 

    3)  How can automated credit card payments be setup for "pay later" scenarios?     For example:  Someone may use a CiviContribute page with a price set to commit to paying a $2400. annual membership fee, a $1000 building fund commitment, and a voluntary donation to the music fund for $1500.  They do not want to pay the full $4,900. when submitting the form so they check the box for "I'd like to pay some of this amount later."        They want to make an initial payment on their credit card, and set up a schedule of automated repeating credit card transactions for the remainder. ( ie an ARB subscription via or a PayPal subscription.)

    4) Can flexible payments be used to cover a failed automated credit transactions? For example, someone sets up an automated credit card transaction of $100. for 12 payments. The first 6 process successfully, the 7th one fails to to card over limit, then the 8th and remaining payments are successful.  The person mails a check for $100. to cover the missed 7th payment.

    1. Mar 07, 2012

      Hi Sarah,

      Thanks for outlining areas that will need to be addressed when we support payment schedules for obligations. I will work on a spec page for that in the coming days - I know it's a high priority for you - and let you know about it once it's ready for review.

  5. Mar 27, 2012

    Not sure that this belongs here, so please relocate if desired.

    Whilst all the improvements on part payments are great, our biggest need is to be able to record a payment against contact A's record and send contact A a receipt then allocate that contribution to a membership/event recorded for a contact B (and perhaps contacts C, D etc)

    About 10% of our memberships are actually gifts from an existing or previous member (contact A) to a friend or relation (contact B) .

    Also when we run educational events,  a local group ( Contact A - an ORG sub-class)  within our Association may pay the registration fees for the volunteers ( contacts B, C, D etc) who are active in that group.

    In either case it is not appropriate to record the contribution against contact B( C, D etc).

    1. Mar 27, 2012

      Thanks, Joanne. This is a great place for these sorts of comments. I'm not sure that we will be able to get the ability for A to pay for B in general. Currently there is an 'on behalf of' functionality in some areas of CiviCRM, but it may not meet all of your needs. These are both points that we are aiming to address.



  6. Apr 08, 2012

    Joe - I have a question about the section titled "End-user submitting payments against his own partially paid obligations"

    Would this functionality cover the 2 scenarios:

    a) The obligation has had nothing paid against it to date.  For example:    Someone in the back-office created an obligation of $2000. for a contact, "John Doe". Later on, John Doe is looking at his contact dashboard and would like to make a payment. Is this possible?

    b) The user is visiting their dashboard, and sees an obligation of $2400. They want to put it on their credit card as 12 monthly payments of $200.  ( ie using the Automated Recurring Payments feature with or PayPal)


    1. Apr 08, 2012

      Hi Sarah,

      On the topic of end-users submitting payments against outstanding obligations, the total of what we have so far is the textual description of the UI written above under "End-user submitting payments against his own partially paid obligations."  My understanding is that these features would not be part of phase 1.

      To your specific questions:

      a) Yes, that's the idea, and is pretty much what's meant to be described in the "End-user submitting payments against his own partially paid obligations" section above.

      b) I guess this could be called "scheduling recurring payments against existing obligations." I don't think we've considered this feature yet as far as the UI goes; it's possible the schema as written would support it when the UI and scheduling code is built for it.

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.