Forum OpenACS Development: Donationware discussion

Several of us recently had a good discussion on IRC about what it would take to implement a decent Donation package on top of the payment gateway. I'm posting a (very lightly edited) log here in the hopes that others might have some ideas and thoughts to follow up with.

============================================
<redmonk> one question is what kind of donations can be accepted
<redmonk> obviously the palce to start is single-payment-credit-card transactions
bartt [~mailto:bart@dsl092-028-174.sfo2.dsl.speakeasy.net] has joined #oacs-donate
<bartt> Hi
<redmonk> hi bartt
<bartt> Hi redmonk
<bartt> Could you outline your thoughts for a donation packages?
<redmonk> sure.
<redmonk> I'm not totally familiar with the gamut of donation-ware, but as I see it, the goal is simple:
<redmonk> allow users to donate certain amounts to an organization, optionally specifying which project the donation is to go to
<redmonk> project/sub-org/whatever
<redmonk> another feature is often monthly EFT processing
<redmonk> for ongoing support
<redmonk> (electronic funds transfer)
<redmonk> i think an org would like to be able to:
<redmonk> define the various "targets" for donations
<redmonk> they might be projects, sub-organizations, or whatever.
<redmonk> "categories" might be a more generic term. not sure
<redmonk> talli should be in here
<redmonk> i would assume some integration so that notification can be used, for example, for monthly reminders to previous donors, or receipts to ongoing donors
<redmonk> also integration with the user system so that a site can provide custom content for donors
<redmonk> (i worked for a company that did this: they had custom content for their major donors)
<redmonk> so there's another possible requirement: gift tracking by user
<redmonk> that's a arough sketch
<redmonk> thoughts?
<bartt> What do you mean by EFT?
<redmonk> <redmonk> (electronic funds transfer)
<redmonk> automatic w/d
<redmonk> not sure how complicated that is. I'm sure it's a mess.
<bartt> Does that cover: CC, eCheck, PayPal and what not?
<redmonk> not CC
<bartt> ACH
<bartt> = Automatic Clearing House.
<jadeforrest> Paypal can do Credit Card though.
<bartt> Sure
<bartt> But requires people to signup with paypal.
<redmonk> i honestly don't know a lot about the various financial transactions.
<bartt> In addition to providing their CC over the web
<jadeforrest> I don't think you actually have to.
<jadeforrest> True.
<bartt> With the payment gateway available it would be easier to handle CC directly.
<redmonk> initially I'm just looking at building on the payment gateway
<redmonk> yes
<bartt> Then you should stick to CC
<jadeforrest> So far, what you've outlined is very valuable redmonk.
<bartt> As that is what the payment gateway can handle.
<redmonk> yeah
<jadeforrest> The payment gateway is CC only so far.
<redmonk> thanks jade
<bartt> All other methods require different sets of info.
<jadeforrest> Although someone was talking about bank transfers recently, I think.
<redmonk> anyone know whre the api docs for the payment gateway are?
<bartt> Right, transfers that typically are handled through ACH
<redmonk> i haven't been able to find them
<bartt> Which you can not contact directly bug go through your back
<bartt> s/back/bank/
<bartt> I honestly don't know if there is a bank neutral protocol for bank transfers that one could use.
<jadeforrest> I don't either. Who has been working on that?
<jadeforrest> Was Janine involved?
<bartt> I don't know, doubt it.
<bartt> Unless it was for MIT
<redmonk> is it collaboraid or talli's company that's working on CRM?
<bartt> Don't know
<bartt> Let's go back to donations.
<redmonk> of course
<redmonk> any obvious features I've missed?
<redmonk> (i'm sure they're tons)
<jadeforrest> Let me think:
<bartt> I'm thinking that combining various transaction protocols in a single service contract is the wrong thing to do.
<jadeforrest> Allowing a user to start and stop automatic payments
<jadeforrest> Bart: maybe there should be a couple, for different types?
<bartt> Rather I advocate service contracts for eChecks, another one bank transfers and so on.
<jadeforrest> Perhaps some sort of history of payments for the year, so you can see how much you paid out.
<redmonk> bartt: yes i agree
<bartt> Packages can then pick and choose.
<jadeforrest> And an email after the end of year for taxes purposes.
<bartt> And adjust their work flow to the flow of the service contract.
<redmonk> payment history is great; esp. since donations to some orgs are tax-deductible
<jadeforrest> And a way for the non-profit to contact donors and ask them for special donations.
<bartt> So I would argue that you can safely start with payment gateway for CC
<jadeforrest> redmonk: yes, exactly!
<bartt> Donors should be able to see what they have donated and when the next donation is up.
<jadeforrest> Bart: I think starting with CC would be a good first step, and then after that moving to other types in version 2.
        redmonk nods
<jadeforrest> redmonk: I really like your idea of earmarked contributions.
<jadeforrest> redmonk: but it's up to you and your clients of course.
<redmonk> of course
<jadeforrest> redmonk: for CC or other types of payment.
<bartt> Donors should be able to cancel ongoing donations.
<redmonk> bartt: yes, jade mentioned start/stopping automatic w/ds
<jadeforrest> You should also be able to look up donors by how much they've donated. All donors who have contributed more than $500 in the last year, for example.
<jadeforrest> They could get special thanks or whatever.
<jadeforrest> OPB gives theater tickets for example.
<jadeforrest> Oops, Oregon Public Broadcasting.
<jadeforrest> Hmm, what else?
<bartt> redmonk: can you describe how you intend to handle transactions?
<jadeforrest> People should be able to specify that they don't want donation related spam. :)
<redmonk> bartt: i have no idea yet. ;)
<redmonk> i'm new to this. I need to see the payment apis
<bartt> E.g. what to do when a CC fails.
<redmonk> well, notify the user of course
<redmonk> in that case
<redmonk> either on the site or by email
<bartt> When immediately? After a retry?
<redmonk> i would say after a retry or two
<bartt> Will you check their CC before charge the card.
<jadeforrest> I think a lot of that can probably be resolved by looking at how ecommerce does it, no?
<bartt> What should a donor do when he/she receives an email that the transaction failed.
<bartt> Ecommerce solved it but the implementation is a mess!
<redmonk> what does ecomm do?
<bartt> Also ecommerce has to deal with partial payments for partial shipments.
<bartt> And adds tax and shipping.
<bartt> Here you have a set amount for a single payment.
<redmonk> yes
<bartt> That makes it a lot easier.
<redmonk> yeah
daveb [~mailto:dave@alb-24-194-208-106.nycap.rr.com] has joined #oacs-donate
<jadeforrest> Dave suggested we log this. That seems like a good idea to me. Do you guys want to do it, or shall I
<bartt> You will have to record each donation amount for each cycle as well as the amount charged to the card.
<redmonk> welcome daveb
<daveb> just lurking :)
<bartt> So that you have record of the agreed upon amount and the transaction.
<redmonk> yeah, i assumed a record of each transaction
<bartt> The CC gateway already records all communication with the CC processor.
<redmonk> version 1 i think won't do automated transactions
<redmonk> but that depends on who's paying for it
<redmonk> ;)
<bartt> OK here's the flow for a successful donation:
<bartt> Donor fills out forms.
<bartt> Enters amount and CC details.
<bartt> These are being recorded.
<bartt> (Note: safeguard those CC details)
<bartt> Contact the CC gateway and run the transaction.
<bartt> That is approve the card and charge the card in a single step
<bartt> (Or charge immediately after approval. I think the CC gateway separates the 2 steps, even though most CC processors can lump them together.)
<bartt> Present a thank you note.
<bartt> Record the transaction for this donation.
<bartt> Donor can now find his/her donation on his account page.
<bartt> Failed donation:
<bartt> Various failures possible:
<bartt> No connection to CC processor.
<bartt> No response from CC processor
<bartt> CC card not valid.
<bartt> Not enough money in account.
<bartt> Not all of these cases can be distinguished.
<redmonk> heh. lovely
<redmonk> don't forget Invocation of Murphy's Law
<redmonk> ;)
<redmonk> good info, bartt
<bartt> Sorry, phone call
<redmonk> np
<bartt> No connection / no response for example is returned by CC gateway as failure-retry
<bartt> Indicating that the failure could be temporal.
<bartt> It is up to the implementation of the CC gateway to decide which failures can be retried.
<bartt> Others such as CC not valid will return failure.
<redmonk> hm.
<redmonk> so it's the gateway that does not differentiate
<bartt> For those you can ask the donor to review their CC info.
<bartt> Not always redmonk
<redmonk> hm
<bartt> Sometimes the protocol that the CC implementation uses can't tell.
<redmonk> ah
<bartt> Again take the no connection / no response
<bartt> These problems are most likely connectivity issues.
<bartt> And therefore temporal.
<redmonk> right
<bartt> Anyway, I've been running an on-line store for over a year now based on CC gateway
<redmonk> cool
<bartt> without any problems
<redmonk> ok. e-comm based? or no?
<bartt> Yes ecommerce based.
<redmonk> ah.
<bartt> http://www.7-sisters.com/
<redmonk> how do you handle connection problems? do you cancel the transaction, or do you wait and try again later?
<bartt> So failure-retry should be retried after an interval.
<bartt> ecommerce has several scheduled procs that do this.
<bartt> Failed transactions are flaged.
<bartt> There is a difference between permanent failures and temporal failures.
<bartt> Temporal failures are being retried.
<bartt> If the transaction keeps failing the transactions should eventually be marked as permanent.
<bartt> At that point you'd contact the donor to come back to the site and correct the problem.
<bartt> Or you ask the admin to take a look at it first.
<redmonk> right
<bartt> To see if it is say a configuration problem.
<bartt> Instead of a failure of the donor.
<redmonk> right
<bartt> Like not enough funds.
<bartt> (Which CC don't tell you. You'll only know that the transaction fails)
<redmonk> interesting. i would have thought that not enough funds would be a common - and properly delineated - error
<bartt> Oh no, think privacy!
<bartt> :)
<redmonk> heh
<bartt> You could use that information to find out how much money there is in the account.
<redmonk> true
<bartt> Anyway I have to get back to work.
<bartt> Think about these issues.
<redmonk> ok. thanks for all the insight, bartt
<bartt> Take a look at ecommerce
<bartt> The code is crap.
<redmonk> heh
<bartt> But I did a major overhaul of the transaction system.
<redmonk> ok, will do.
<bartt> Which, at this point is 99% correct.
<jadeforrest> :)
<bartt> I recommend you to take a look at payment-gateway and authorize-gateway.
<jadeforrest> Perhaps we should post this log on the Forums, and see if we get more comments?
<bartt> The latter is an implementation of the first.
<bartt> The service contract is not documented.
<bartt> But authorize-gateway is.
<redmonk> jade: i do think it's a good idea to post the log
<bartt> Last but not least, you can get a test payflowpro account.
<redmonk> wanna do that for us?
<bartt> This you can use this account to test your code with.
<bartt> It's free.
<redmonk> cool
<bartt> See notes in the ecommerce docs.
<redmonk> ok
<redmonk> thanks again bart
<bartt> All this has also been mentioned on the forums.
<bartt> np
<bartt> See ya
bartt has left #oacs-donate [:]

I've mapped out a basic workflow for a donation system from the User's POV.

http://media.redmonk.net/oacs/donation/donation-workflows-1.pdf

It's rough, and somewhat incomplete perhaps, but please take a look and comment if you like.

--Steve

Hi Steve,

Cynthia led an aD project some years ago for a donor service provider website, GivingCapital.  They're still running at www.givingcapital.com, but they've moved away from the campaign/donation model to a private foundations model (so you can't see the donations subsite anymore).  You might try contacting them to see if they're willing to release some of the donations source for ideas.

It was started with ACS 2.x, and slowly moved up to the level of ad_page_contract when that was out, so much of the code would be out-of-sync with OACS.  But the workflow might be interesting.  It had a campaign creation wizard, matching fund drives, white label (branded) templating, sub-accounting, etc.  One of the things I saw 'missing' from your workflow is refunds.  Important if you let users type in their own donation amounts, regardless of a confirmation page.  There was also an alternate 2-click workflow for repeat donors.

Well, good luck...

One more noteworthy bit of information about Automatic Clearing Houses. Checkout Authorize's eCheck program at http://www.authorizenet.com/solutions/echeck.php. One would be able to build upon the code of the authorize-gateway package which processes credit cards through Authorize.net.

Both packages would have the same type of connection to Authorize.net as well as the API. The difference is in the information exchanged between the gateway and Authorize.net.

/Bart