Forum OpenACS Development: RFC: Donationware Spec

Posted by Steve Ivy on
This is a spec for a new Donation package based on payment gateway. Please feel free to comment - I'll likley incorporate te good stuff back into the document (original here)

Donation Notes

Introduction #

Purpose: The Donation package enables organizations to accept and process credit card based transactions of user-specified amounts. #

    Background: While the eCommerce package for OpenACS provides shopping and credit card processing capabilities sufficient for most uses, it does not adequately address the needs of the non-profit or 503(c) organization that needs to accept and process credit card based gifts. #

      These features are mainly centered around allowing the User to specify the amount of each donation. Also, by using standard OpenACS objects where applicable, other packages in a community server can make use of Donation services. #

        Links #

        Features #

        Donation Package (V1) #

        • User-Level Features
          • Users can donate an arbitrary sum, to be drawn from a credit card account
            • Users can optionally specify a Campaign, Department, or sub-category to donate to.
              • User can view donation history and pending donations
                • User can contact an Administrator about a particular Donation
                • Administration Features
                  • Organization can define Campaigns/Sub-categories.
                    • Note: This system will not be a complete campaign management system. The term campaign is used here only to designate an organization-defined label to be applied to a transaction when specified by the User when donating.
                    • Organization can view a list of recent donations
                      • Organization can select a Donation and refund the User that amount.
                        • Further reporting features are planned for future releases
                        • Package Features
                          • A User is a Site member, enabling integration with other OACS packages.
                            • Provides an API for accessing Donation information from other parts of OpenACS.
                              • Interfaces with the Payment Gateway to provide CC processing
                                • Maintains an Activity Log for System Administration and troubleshooting purposes.
                                • Suggested Features - Wednesday, 23. July 2003
                                  • Use the workflow package (Talli Somekh)
                                    • Use categories package (Talli Somekh)
                                      • "specify whether donations are tax-deductible, or whether campaigns are tax-deductible" (Jade Rubick)

                                      Donation Reporting Package (Planned) #

                                      • Organization can view a Donor list and donation amounts.
                                        • Organization can view Donor History
                                          • Organization can view list of donations and totals per Category for specified time periods.

                                            Donation CRM Integration (Possible Future) #

                                            • Investigate integration with MuseaTech OpenACS CRM package.

                                              Use Cases #

                                              Main User Use Cases #

                                              • Donation
                                                • Success
                                                  • After browsing the site, the User decides to Donate, optionally to a particular Compaign
                                                    • The user clicks a "Give" or "Donate" link that brings them to the Donation page.
                                                      • Optionally:
                                                        • User clicks a "Give To This Campaign" or "Donate to this Campaign" link on a Campaign-related page
                                                        • If the User is a Member, and is logged in, then they continue the process. If the User is not a Member, or is not logged in, they are directed to the "Register/Login" page where they must either Register as a Site Member or Login.
                                                          • Note: Required information will include full name, address, phone, email.
                                                            • A privacy statement should be provided and respected.
                                                            • If the User clicked a Campaign-specific Donation link, the Capaign is pre-selected in the "Donation details" screen. Otherwise the default value is preselected. In either case the User has the option of changing their Campaign selection.
                                                              • The User enters a Donation amount, either by entering an arbitrary amount in a text field, or possibly by selecting from a pre-determined list of donation amounts.
                                                                • User enters Credit Card (CC) Name, Number, and Expiration date.
                                                                  • User enters Full Name, Address, Phone, Email, etc. Auto-Fill where possible from User's registration info.
                                                                    • User clicks "Submit Donation".
                                                                      • User is presented with a Confirmation screen, listing the Donation Details, CC Info, and User Inforrmation.
                                                                        • If information is correct, User clicks "Confirm Donation".
                                                                          • User is presented with Success and Thank You screen.
                                                                          • Failure - Info incorrect
                                                                            • User clicks "Confirm Donation"
                                                                              • User is presented with an Error screen, informing them that there was a problem processing their donation and to please check the information they entered.
                                                                                • User can re-submit the donation.
                                                                                • Failure - Cannot settle
                                                                                • View Donation History
                                                                                  • Contact Administrator about a Donation

                                                                                    Administrative Use Cases #

                                                                                    • Install and Configure
                                                                                      • Add Donation instance to Site
                                                                                        • Configure Donation instance
                                                                                          • Admin opens the sitemap for their acs-subsite
                                                                                            • Admin clicks "set parameters" on the mounted Donation instance
                                                                                              • Admin sets parameters to applicable values for this instance
                                                                                              • Add Campaign to Donation instance
                                                                                                • Admin opens Donation Admin page
                                                                                                  • Admin clicks "Add Compaign/Sub-Category"
                                                                                                    • Admin enters Campaign information (name, etc)
                                                                                                      • Admin clicks "Add"
                                                                                                    • Reports
                                                                                                      • View Recent Donations
                                                                                                        • Admin visits Donation Reports page
                                                                                                          • Admin clicks "Recent Donations"
                                                                                                            • Admin is presented with a reverse-chronological listing of the last n donations, whether they are pending or captured, and the Donor.
                                                                                                            • View Donor Details
                                                                                                              • Admin visits Recent Donations page
                                                                                                                • Admin clicks the "Details" link next to a Donor
                                                                                                                  • admin is presented with the Donor Details page containing name, address, and donation information for a donor.
                                                                                                                  • View Donation Details
                                                                                                                    • Admin visits the Recent Donations page
                                                                                                                      • Admin clicks "Details" link next to a Donation
                                                                                                                        • Admin is presented with the Donation Details page.
                                                                                                                      • Actions
                                                                                                                        • Refund Donation
                                                                                                                          • Admin may be contacted by a Donor regarding a problematic donation, or through the payment processing system.
                                                                                                                            • Admin visits the "Recent Donations" page
                                                                                                                              • Admin clicks "Donation Details" next to the relevant donation.
                                                                                                                                • Admin clicks "Refund Donation to Donor".
                                                                                                                                  • Admin is presented with the "Refund Donation" page
                                                                                                                                    • Admin enters relevant data for Reason, authorization, etc.
                                                                                                                                      • Admin clicks "Confirm Refund"

                                                                                                                                    System Admin and Troubleshooting Use Cases #

                                                                                                                                    • View Activity Log
                                                                                                                                      • SysAdmin opens the "Donation System Admin" page
                                                                                                                                        • SysAdmin clicks "View Activity Log"
                                                                                                                                          • SysAdmin is presented with a list of recent activity by the donation system, including card authorizations, captures, notices and errors
                                                                                                                                          • View Transaction Details
                                                                                                                                            • SysAdmin opens the Activity Log page
                                                                                                                                              • SysAdmin clicks on "Details" link next to a Transaction
                                                                                                                                                • SysAdmin is presented with a page listing details about the Transaction

                                                                                                                                                Future (Planned for v1.0+) Use Cases #

                                                                                                                                                • Administrative Use Cases
                                                                                                                                                  • View Donor List
                                                                                                                                                    • Admin visits Donation Reports page
                                                                                                                                                      • Admin clicks on "View Donor List"
                                                                                                                                                        • Admin is presented with sorted (alpha or by donation amount) list of Donors
                                                                                                                                                        • View Donor History
                                                                                                                                                          • Admin visits Donor Details page
                                                                                                                                                            • Admin clicks "View History" link next to a Donor
                                                                                                                                                              • Admin is presented with a reverse-chronological* list of Donations for this Donor.
                                                                                                                                                                • * Newest transactions are listed first

                                                                                                                                                            Posted by Steve Ivy on
                                                                                                                                                            Argh - messed up the links to related docs on that post: The correct URLs for the associated documents are:
                                                                                                                                                            3: Re: RFC: Donationware Spec (response to 1)
                                                                                                                                                            Posted by Jarkko Laine on
                                                                                                                                                            Hey Steve,

                                                                                                                                                            One thing that I didn't find from the specs is the possibility to accept anonymous donations. I don't know if there are any legislative or technical reasons why it wouldn't be feasible, but in practice I could think that there is quite a few people who would like to make their donations incognito.

                                                                                                                                                            4: Anonymous Donations (response to 3)
                                                                                                                                                            Posted by Steve Ivy on

                                                                                                                                                            That's an interesting idea, though I'm not sure if it's possible using a credit card. If you wanted to remain anonymous, you may have to send a money order by mail - old skool but might be less traceable. ;)

                                                                                                                                                            As far as legislative reasons, I don't know.

                                                                                                                                                            5: Re: Anonymous Donations (response to 4)
                                                                                                                                                            Posted by russ m on
                                                                                                                                                            perhaps "anonymous" isn't the right term there, since CC transactions can't be anonymous, but I do think the requirement that someone register at the site to be able to donate places an aditional barrier between the decision to donate and the money arriving in the destination account.

                                                                                                                                                            Also, if they register in order to donate and then forget their password, if they want to come back and donate again they'll need to make up a new bogus email address or go through a password retrieval process in order to be able to give you more money (again, a point where you're potentially going to lose them and their money).

                                                                                                                                                            I'd suggest that you record the donators info if they're a logged-in user, but also allow users who are not currently registered or logged in to donate...

                                                                                                                                                            6: Re: Anonymous Donations (response to 5)
                                                                                                                                                            Posted by Jarkko Laine on
                                                                                                                                                            Agree that cc transactions can't be really anonymous, but if (and when) we are not storing the card information on the server and tell that to customer, I think what Russell says is as anonymous as it gets with the current infrastructure. Dunno what's going to be on our account listing, though, since I've never received a cc payment, but I'd think the name is not there :)

                                                                                                                                                            Of course there's emerging technologies that make real anonymous payment methods in internet possible and I think we should even follow how these things evolve.

                                                                                                                                                            7: Re: RFC: Donationware Spec (response to 1)
                                                                                                                                                            Posted by russ m on
                                                                                                                                                            My point wasn't so much about being anonymous, but that every hurdle a user has to jump through between deciding "that's a good cause, I'll make a donation" and the money appearing in your bank account is another place where they may potentially decide it's all to hard and not complete the transaction.

                                                                                                                                                            Requiring someone to give you their email address and come up with a password is bad enough, but the case when someone comes back later to make another donation and has to recover their password in order to do it is likely to lead to zero repeat donations from anyone other than regular site users. This is surely not what you want.

                                                                                                                                                            I'd think that what you want to present to users is a "make a donation" or "donate to this campaign" button on the refering page, which takes them to a page where they optionally enter some personally identifying information (perhaps filled out for them if they're already regiistered and logged in), potentially select from a list of campaigns (with the correct one pre-selected if they clicked a "donate to this campaign" button), fill in their CC info and then click "donate"...

                                                                                                                                                            registrations are valuable, but surely money is more valuable...

                                                                                                                                                            8: Re: RFC: Donationware Spec (response to 7)
                                                                                                                                                            Posted by Malte Sussdorff on
                                                                                                                                                            If a user wants to make a donation, he has to fill in a minimum amount of data. Name, address and CC card. This is information we can store. If we ask for an email (OPTIONAL) it should not be too much of a hassle for the user. Password will be send to his email address once he hits the donate buttom. Log him into the system, and set a cookie unless his email bounces :).

                                                                                                                                                            If the user returns and wants to make a new donation, he should be shown the values already filled in (name, address, amount, cc info), thanks to the cookie. Once the donation is made, he should recieve an email about it (again, if he supplied a valid email only).

                                                                                                                                                            As for anonymous donations. Is it legal? Or more precise, is it legal to accept them? Just wondering about a lot of skandals we had here with anonymous donations as this can be used for money laundring. If it is, make sure you support it, one way or another, though I personally would never like to forfeit my tax benefit that comes with donations :).

                                                                                                                                                            9: Re: RFC: Donationware Spec (response to 8)
                                                                                                                                                            Posted by Jarkko Laine on
                                                                                                                                                            I'm not sure about the legality of anon. donations in different countries (that's why I asked it), but at least you can easily drop a few thousand bucks into Salvation Army pot without anyone coming to ask your ID or that are you trying to wash your money ;-)
                                                                                                                                                            Posted by Steve Ivy on
                                                                                                                                                            it is likely to lead to zero repeat donations from anyone other than regular site users. This is surely not what you want.

                                                                                                                                                            This is true. I'm trying to remember now why I designed the system to require membership, and having a hard time. I'll look at it again and see about changing it.

                                                                                                                                                            Ok, some of it is coming back to me: requiring site registration gave us a way to use the existing user table for donors, and extend on OACS's account management features (/pvt/home, etc) for allowing donors to view their donation history, etc. Otherwise I need to build and manage a seperate Donor table, as well as creating the "donor account" pages. Oh, and, um, providing a password scheme to protect them?

                                                                                                                                                            Anyway, if that's what I need to do then that's what I need to do, but that was the reasoning behind it.

                                                                                                                                                            Posted by Jon Griffin on
                                                                                                                                                            Please don't store personal information especially CC info in a cookie. It is bad enough to have it on your server.
                                                                                                                                                            Posted by David Walker on
                                                                                                                                                            Why not use a light version of registration anyway?  If you need to capture that information anyway it seems simpler.  If they return and want to donate more you can match them up with the old entry using cc# or a hash of the cc# since that information is presumably as secret as their password.

                                                                                                                                                            The information needed for a credit card transaction is plenty to create a user.

                                                                                                                                                            Posted by Steve Ivy on
                                                                                                                                                            I've thought about the "make-them-a-member-when-they-donate" scheme, and that might work fine. However, I won't be keeping CC #s around - bad mojo there unless it can be made REAL secure.
                                                                                                                                                            Posted by Steve Ivy on
                                                                                                                                                            Did anyone look at the ERD (last page) in the diagrams I posted?

                                                                                                                                                            I'm not at all sure about that "ORG" entity - what it really means or how to manage it. In the context of an oacs package, I could see this being used in a few possible ways:

                                                                                                                                                            1. Singleton package on the server, limit one org per server. Easy to code, but lousy in terms is features.
                                                                                                                                                            2. Singleton package on the server, use an admin page to manage multiple organizations. Not sure why we'd do this, when there's the option to...
                                                                                                                                                            3. Multiple instances of the package. Each instance maintains organization information in instance parameters. This is where I'm leaning.
                                                                                                                                                            So - how important is it that donations, etc, have an explicit database relationship to "organization"? Thoughts?
                                                                                                                                                            Posted by Malte Sussdorff on
                                                                                                                                                            Ups, I did not want to imply to store the cc information or such in a cookie. I thought about storing it in the database so it could be pulled out from there. The cookie I meant is just the normal OpenACS user-is-permanently-logged-in cookie. To make sure that not someone else can accidently use your credit card to make a donation, you can always ask for the security number on the back of your credit card for verification before executing the transaction.
                                                                                                                                                            Posted by Randy Beggs on
                                                                                                                                                            Just to be sure...

                                                                                                                                                            On your Failure - Info incorrect use case, where the: User is presented with an Error screen, informing them that there was a problem processing their donation and to please check the information they entered.

                                                                                                                                                            Don't re-show the cc # since you're not guaranteed who the person on the other side is; what with password managers, etc.  It's easy enough to login with someone elses account and enter a bogus donation amount you know will fail (such as 80K, 200K, etc.) and pull up the 'correct your info' page.  Only allow adds/deletes of cc #'s, never edits.

                                                                                                                                                            You might consider breaking up the workflow a little bit into separate pages to give the feeling of immediate progress, and less that of a spam collecter.  Maybe like:

                                                                                                                                                            a) enter username/password (two fields only).
                                                                                                                                                            b) enter donation amount, message from donor; show feel-good message from impending recipient.
                                                                                                                                                            c) enter cc# info (collect address at this point)
                                                                                                                                                            d) confirm donation choices (confirm password too)
                                                                                                                                                            e) submit, receipt, thanks, and tax printout

                                                                                                                                                            A last point, in the sysadmin use case you might provide a configuration on the comfort level of 'auth' recieved in order to make the transaction succesful (e.g. zip matches but address does not, name matches but zip does not, etc.).  Depends on the cc processor.

                                                                                                                                                            Oh, and the idea of pre-configured donation amounts, based on the individual campaign or website; in addition to free-form entry is great.

                                                                                                                                                            Posted by Steve Ivy on
                                                                                                                                                            Hi Randy,

                                                                                                                                                            You make some good points here that I want to address in the docs. Esp the confirmation issues and the workflow aspects. Once I have the changes made I'll post somme more comments here.

                                                                                                                                                            Posted by Jorge Garcia on

                                                                                                                                                            just curious about the program you have used to create the ERD in your PDF. Which that program?

                                                                                                                                                            Have you used another program to retouch the ERD?

                                                                                                                                                            Exactly, the links who joins two tables are named, the name is the same of the key.

                                                                                                                                                            Have you added that name 'by hand' or the same program has created it?


                                                                                                                                                            Posted by Steve Ivy on

                                                                                                                                                            I used OmniGraffle on Mac OS X ( The diagram was created mostly "by hand" - the symbols are provided, but there is no underlying understanding of the datamodel by the program. The links between entities are all my doing.

                                                                                                                                                            Posted by Steve Ivy on
                                                                                                                                                            I just posted a new version of the spec ( ).

                                                                                                                                                            I've included some modifications of the donation process, loosely based on Randy's suggestions, as well as including a note that I need to revisit the registered member vs non-registered donor issue. I think it's also easier to read now, with the use cases called out a bit better.


                                                                                                                                                            Posted by Nima Mazloumi on

                                                                                                                                                            what happened to this? Was this package ever implemented. Looking at all the bugs entered in bug-tracker that are really feature requests I think it would be nice to have a package that would list all those requests and allow institutions and individuals to donate to feature requests. Developers can then decide according to their estimation whether they are willing to take over the task to implement the feature.

                                                                                                                                                            If the feature is developed satisfactorily the money is transferred to the developer.

                                                                                                                                                            What do you think?