Single click donations with CiviCRM

Summary

OneClickDonate.php is one of the PHP scripts that is behind CC's one-click-like donation process. The buttons on CC's donation page all lead to this script, which processes any submitted variables and then sends the contributor off to PayPal. Contributor's won't generally even be aware that they have passed through this script; it will appear to them that they went directly from the donation page to PayPal.

The script is located in CC's public git repository.

NOTE: OneClickDonate.php will not work without modifications to a couple other CiviCRM files: CRM/Contribute/BAO/Contribution/Utils.php and bin/ContributionProcessor.php. The necessary patches for those files are here:

• ContributionProcessor.php (scroll down for diff).
• Utils.php (scroll down for diff)

Static variables

There are a couple variables that are statically defined in the script. They are presumed to not need changing on a flexible basis:

# Valid groups that contributors can join.  This is just a safeguard
# to prevent contributors from joining arbitrary groups.  This should
# be an array of group names as they are seen in the CiviCRM admin
# interface, not as they are in the database.  Example:
$valid_groups = array(
    "CC Newsletter",
    "CC Events"
);

# The base PayPal URL for the request (minus the query string)
$paypal_base_url = "https://www.paypal.com/cgi-bin/webscr";

# Email address of site's PayPal account
$paypal_business = "paypal@creativecommons.org";

Predefined variables

There are a few variables that need a default value because they are too important to leave to chance, yet can be overridden by one of the variables under Usage'.

# Default name of item as contributor sees it at PayPal and as recorded in
# CiviCRM.  Can be overidden by passing $_REQUEST['source'].
$paypal_item_name = "Creative Commons Donation";

# Where contributor goes if they cancel contribution at PayPal
# Can be overidden by passing $_REQUEST['cancel_return'].
$paypal_cancel_return = "https://support.creativecommons.org/donate";

# Where user goes when they click "Return to Merchant Site"
# Can be overidden by passing $_REQUEST['return'].
$paypal_return = "https://support.creativecommons.org/thanks";

# The database ID of a message template to use for a receipt email.
# These are the message templates found CiviCRM at:
# <code>CiviCRM -> Administer CiviCRM -> Configure -> Message Templates</code>
$custom_data['receipt'] = "20";

Usage

Anyone can make use of the script from anywhere, but the script expects certain variables to be passed to it. The only variable which is really necessary is amount. Here is a summary of the possible variables, which can be sent by either a GET or POST request:

• amount (required): The amount of the contribution, with no currency symbol. It can be a floating number, but will get rounded to two decimal places if for some reason it has more. Example: ?amount=150
• cancel_return (optional): This is the URL the contributor will be directed to should they for some reason click the "Cancel. Return to $merchant site." link on the PayPal site without having completed the transaction. Will always have a predefined default value should it not be passed. Example (urlencoded): ?cancel_return=http%3A%2F%2Flolz.biz%2Fthanks
• groups (optional): A colon separated list of groups that the user should be subscribed to. The group names are the exact names as they are found in the CiviCRM database, spaces and all. The script will not let users join arbitrary groups. Passed groups that are not in the predefined groups list in OneClickDonate.php will be ignored. Example (urlencoded): ?groups=CC+Newsletter:CC+Events
• pcpid (optional): If this contribution originated from a Personal Campaign Page (PCP), this is the CiviCRM database ID of the PCP page. Example: ?pcpid=8
• premium (optional): If the user has opted for a gift/premium, this is the CiviCRM database ID of the premium they will get. Example: ?premium=12
• return (optional): This is the URL the contributor will be directed to if/when they click "Return to $merchant site." link on the PayPal site after having completed the transaction. Will always have a predefined default value should it not be passed. Example (urlencoded): ?return=http%3A%2F%2Froflcon.org%2Fthanks
  • size (optional): If the premium includes a t-shirt, this is a free-text description of the size. This option is ignored if premium is not set. Example (urlencoded): ?size=Adult+Large
• recur (optional): Defines whether this is to be a recurring contribution, and if so of what type. A passed value of 1 means that the amount will charged to the contributor's PayPal account every month for 12 months. A passed value of 2 means that the amount will be charged to the contributor's PayPal account every month indefinitely. Example: ?recur=1
• sloptout (optional): If this variable is present in the request the contributor's name will not be included in the public supporter list on the CC support site. If the contribution originated from a PCP, the contributor will not show up in the "honor roll" list on the PCP page. The value doesn't matter. If this variable is not passed, the contributor's name will by default be displayed in public supporter listings. Example: ?slopout=LOL
• source (optional): When the contributor is sent to PayPal there is a description displayed letting them know what the payment is for. If this value is passed it will be the text that is displayed to the contributor at PayPal. It is also the text that will be stored in the CiviCRM contribution field "Source," so it can used to identify where the contribution originated such as from the CC Network, a regular donation, a donation widget, etc. A default value is set in the script which will be used if this variable isn't passed. Will always have a predefined default value should it not be passed. Example (urlencoded): ?source=CC+Network+Annual+Membership