Difference between revisions of "Single click donations with CiviCRM"

From Creative Commons
Jump to: navigation, search
(Summary)
(Usage)
 
(59 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
=== Summary ===
 
=== Summary ===
  
OneClickDonate.php is one of the PHP scripts that is behind CC's one-click-like donation process.  The buttons on CC's [https://support.creativecommons.org/donate 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.
+
Creative Commons has developed a modified donation process using CiviCRM which can potentially send a contributor off to the payment processor with as little as a single click. All of the donation buttons on CC's [https://creativecommons.net/donate donation page] utilize this process.
  
 
There are a number of possible benefits to using this method as opposed to regular contribution pages in CiviCRM:
 
There are a number of possible benefits to using this method as opposed to regular contribution pages in CiviCRM:
* The contributor makes a single click to donate on your site.  The less clicks/keystrokes the better chance someone will complete a contribution.  I believe this has been empirically test and demonstrated.
+
* The contributor (potentially) makes a single click to donate on your site.  The less clicks/keystrokes the better chance someone will complete a contribution.  I believe this has been empirically tested and demonstrated (??).
 
* You are no longer limited to designing your contribution pages within the confines/scope of Drupal and CiviCRM.  You can create pages the way you want, wherever you want.  This is especially nice for widgets, or anyone else wanting to help your campaign.  Potentially, people can create their own donate links on their own sites ... it doesn't matter.  And if you run multiple sites, you can place Donate links wherever you want on any of those sites, and it makes no difference whether it's run by Drupal, Wordpress, Joomla, or even made with static HTML.
 
* You are no longer limited to designing your contribution pages within the confines/scope of Drupal and CiviCRM.  You can create pages the way you want, wherever you want.  This is especially nice for widgets, or anyone else wanting to help your campaign.  Potentially, people can create their own donate links on their own sites ... it doesn't matter.  And if you run multiple sites, you can place Donate links wherever you want on any of those sites, and it makes no difference whether it's run by Drupal, Wordpress, Joomla, or even made with static HTML.
* Tired of ''Pending (Incomplete Transaction)'' contribution statuses and bogus contacts for people who never completed a transaction?  This method eliminates those 100% because no contact or contribution will ''ever'' end up in the database ''until'' a contribution has been completed at PayPal.
+
* Tired of ''Pending (Incomplete Transaction)'' contribution statuses and bogus contacts for people who never completed a transaction?  This method virtually eliminates those because a contact/contribution is not created in the CiviCRM database until an IPN/notification is received from the payment processor.
 +
* As long as the "one-click" scripts are in place, the state of your CiviCRM install doesn't really matter from a user perspective, at least as it relates to contributions.  This has been useful for CC when upgrading -- not having to worry about disrupting live contributions should an upgrade encounter problems.
  
[http://code.creativecommons.org/viewgit/civicrm.git/plain/bin/OneClickDonate.php?id=c8e8348be0822f230eefe1a44ef265c4981f1902 The script] is located in CC's public [http://code.creativecommons.org/viewgit/ git repository].
+
The system is currently comprised of two files: a class file which contains all the code, and a simple router/wrapper script which receives and routes incoming requests:
  
'''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:
+
* [http://code.creativecommons.org/viewgit/civicrm.git/tree/bin/OneClick.class.php?h=cc_production_3.3.5 OneClick.class.php]
 +
* [http://code.creativecommons.org/viewgit/civicrm.git/tree/bin/OneClick.php?h=cc_production_3.3.5 OneClick.php]
  
* [http://code.creativecommons.org/viewgit/civicrm.git/diff/bin/ContributionProcessor.php?id=c8e8348be0822f230eefe1a44ef265c4981f1902&id2=87fdecb84f70e4e46af741de3430844ee2d9333c ContributionProcessor.php] (scroll down for diff).
+
=== Special Considerations ===
* [http://code.creativecommons.org/viewgit/civicrm.git/diff/CRM/Contribute/BAO/Contribution/Utils.php?id=5aa2b163e0f761e7cdd15adb6d966667be659ddc&id2=87fdecb84f70e4e46af741de3430844ee2d9333c Utils.php] (scroll down for diff)
+
This method is known to work with CiviCRM versions '''2.2.7''', '''3.1.1''', '''3.1.3''', '''3.1.6''' and '''3.3.5'''. It should work fine with any version in the 2.2.x or 3.1.x line.
  
Once the scripts are in place and modified to suit your unique setup and needs, then you simply need to run ''bin/ContributionProcessor.php'' periodically to pull new contributions into CiviCRM. CC does this via a cronjob that looks something like:
+
It currently works with PayPal and Google Checkout.
  
<pre>
+
=== Configuring CiviCRM for use with OneClick ===
*/15 * * * * wget -O - -q -t 1 "https://support.creativecommons.org/sites/default/modules/civicrm/bin/ContributionProcessor.php? \
+
 
name=XXXXXXXX&pass=XXXXXXXX&key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXX&ppID=5&ppMode=live&type=paypal" &> /dev/null"
+
The OneClick system may require you to make a few configurations in CiviCRM, depending on your needs and how you plan to use OneClick.
</pre>
+
 
 +
* '''General''': these things should be done no matter what:
 +
** ''Administer -> Customize -> Custom Data'': here we create a custom data field that is somewhat for internal use but is required for email receipts to work with Google Checkout, but could be useful for future reference or debugging.  Create a 'New Group of Custom Fields' ''Used For'' - Contributions of ''Type'' - Donation.  The ''Group Name'' doesn't matter. Now add a new ''Custom Field'' to the group with these attributes:
 +
*** ''Field Label'' (*exactly*): 'OneClick Custom Data'
 +
*** ''Data and Input Field Type'': Alphanumeric - Text
 +
*** ''Database field length'' (arbitrarily large): 2000
 +
 
 +
* '''Email receipts''': if you'd like to automatically send your donors a receipt by email, then you'll need to do these things:
 +
** ''Administer -> Configure -> FROM Email Addresses'': add a new FROM address and the Description field must be *''exactly''*: 'OneClick Email Receipts'.  This is the address the receipt will appear to come from.  The address will also be Bcc'd on the receipt, and will also be the Reply-To address.
 +
** ''Administer -> Configure -> Message Templates'': create a new template.  This will be the body of the receipt email, and the ''Message Subject'' of the template will become the email Subject:.  Note the database ID of the template, because you will need to pass this into the system at some point (see ''Usage -> receipt'' below).
 +
 
 +
* '''Google Checkout''': if you plan to utilize Google Checkout, then you need to do these things:
 +
** ''Administer -> Configure -> Global Settings -> Payment Processors'': create a new payment processor of type 'Google Checkout'' and the Name field must be *''exactly''*: 'Google Checkout API Access'.  Fill in the rest of the fields as necessary.
 +
** Login to your Google Checkout merchant account and go to ''Settings -> Integration'' and set the ''API callback URL'' to: <nowiki>https://<yourdomain>/sites/default/modules/civicrm/bin/OneClick.php?oc_action=googleipn</nowiki>
 +
 
 +
* '''Optional''':
 +
** ''Administer -> Customize -> Custom Data'': here we create a custom data field that can be used to determine whether a user wants their name to appear in a list of recent donors on your site. NOTE: by itself this field will do nothing for you.  It is simply a flag against which you can write your own code to display, or not, your donor names on your site.  Use the same custom data group from ''General'' above.  Now add a new ''Custom Field'' to the group with these attributes:
 +
*** ''Field Label'' (*exactly*): 'OneClick Supporter List'
 +
*** ''Data and Input Field Type'': Alphanumeric - Text
 +
*** ''Database field length'': 256
  
=== Static variables ===
+
===Variables===
  
There are a couple variables that are statically defined in the script. They are presumed to not need changing on a flexible basis:
+
All of the following are found and set in the file ''bin/OneClick.class.php''.  There are a few more variables, but the following are the only ones you should change unless you know what you're doing.
  
 
<pre>
 
<pre>
# 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)
+
// Turn IPN debuggin on/off. Logs to CiviCRM's default log file.
$paypal_base_url = "https://www.paypal.com/cgi-bin/webscr";
+
const OC_DEBUG = TRUE;
  
# Email address of site's PayPal account
+
// Valid groups that users can join.  This is just a safeguard to prevent
$paypal_business = "paypal@creativecommons.org";
+
// users from joining arbitrary groups
</pre>
+
public $_valid_groups = array(
 +
    'CC Newsletter',
 +
    'CC Events'
 +
);
  
=== Predefined variables ===
+
// IPN callback URL for PayPal
 +
$_paypal_notify_url = 'https://$domain/sites/default/modules/civicrm/bin/OneClick.php?oc_action=paypalipn';
  
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'''.
+
// Email address of site's PayPal account
 +
$_paypal_business = 'paypal@creativecommons.org';
  
<pre>
+
// Minimum contribution amount, anything lower will be kicked back.
# Default name of item as contributor sees it at PayPal and as recorded in
+
$_min_amount = '5';
# CiviCRM. Can be overidden by passing $_REQUEST['source'].
+
   
$paypal_item_name = "Creative Commons Donation";
+
// An array of URLs that should be notified when an incoming
 +
// contribution (via IPN) is successfully processed.
 +
$_notify_urls = array(
 +
    'https://creativecommons.net/a/invite/'
 +
);
  
# Where contributor goes if they cancel contribution at PayPal
+
// Default name of item as contributor sees it and as recorded in CiviCRM.
# Can be overidden by passing $_REQUEST['cancel_return'].
+
$_item_name = 'Online Contribution: Support Creative Commons';
$paypal_cancel_return = "https://support.creativecommons.org/donate";
 
  
# Where user goes when they click "Return to Merchant Site"
+
// Where contributor goes if they cancel contribution at payment processor
# Can be overidden by passing $_REQUEST['return'].
+
$_cancel_return = 'https://support.creativecommons.org/donate';
$paypal_return = "https://support.creativecommons.org/thanks";
 
  
# The database ID of a message template to use for a receipt email.
+
// Where user goes when they click "Return to Merchant Site"
# These are the message templates found CiviCRM at:
+
$_return = 'https://support.creativecommons.org/thanks';
# CiviCRM -> Administer CiviCRM -> Configure -> Message Templates
 
$custom_data['receipt'] = "20";
 
 
</pre>
 
</pre>
  
 
=== Usage ===
 
=== 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:
+
Anyone can make use of OneClick.php from anywhere, but the script expects certain variables to be passed to it. The only variables which are absolutely necessary are '''oc_action''', '''pp''' and '''amount'''. Here is a summary of the possible variables, which can be sent by either a GET or POST request:
 +
 
 +
*'''oc_action''' (required): The value of this should ''always'' be 'donate'. The only other valid values are ones sent by the payment processor.  Example: <code>?oc_action=donate</code>
 +
 
 +
*'''pp''' (required): The payment processor to use.  Presently it can be one of <strong>paypal</strong> and <strong>gc</strong> (for Google Checkout).  Example: <code>?pp=paypal</code>
  
 
*'''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: <code>?amount=150</code>
 
*'''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: <code>?amount=150</code>
  
*'''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): <code>?cancel_return=http%3A%2F%2Flolz.biz%2Fthanks</code>
+
*'''cancel_return''' (optional): This is the URL the contributor will be directed to should they for some reason click a Cancel link on the payment processor's site without having completed the transaction.  Will always have a predefined default value should it not be passed.  Example (urlencoded): <code>?cancel_return=http%3A%2F%2Flolz.biz%2Fthanks</code>
  
*'''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): <code>?groups=CC+Newsletter:CC+Events</code>
+
*'''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.  OneClick will not let users join arbitrary groups.  Passed groups that are not in the predefined groups list in $_valid_groups will be ignored.  Example (urlencoded): <code>?groups=CC+Newsletter:CC+Events</code>
  
 
*'''pcpid''' (optional):  If this contribution originated from a Personal Campaign Page (PCP), this is the CiviCRM database ID of the PCP page.  Example: <code>?pcpid=8</code>
 
*'''pcpid''' (optional):  If this contribution originated from a Personal Campaign Page (PCP), this is the CiviCRM database ID of the PCP page.  Example: <code>?pcpid=8</code>
  
 
*'''premium''' (optional): If the user has opted for a gift/premium, this is the CiviCRM database ID of the premium they will get.  Example: <code>?premium=12</code>
 
*'''premium''' (optional): If the user has opted for a gift/premium, this is the CiviCRM database ID of the premium they will get.  Example: <code>?premium=12</code>
 +
**'''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): <code>?size=Adult+Large</code>
  
 
*'''receipt''' (optional): This is the database ID of the message template to use when generating a receipt email to the contributor.  These are the message templates found in CiviCRM at ''CiviCRM -> Administer CiviCRM -> Configure -> Message Templates''. This functionality allow you to send a different receipt message based on various criteria, whatever they may be.  You can use any, all or none of a few variable tokens in the templates.  They are pretty much self-explanatory and they are these:
 
*'''receipt''' (optional): This is the database ID of the message template to use when generating a receipt email to the contributor.  These are the message templates found in CiviCRM at ''CiviCRM -> Administer CiviCRM -> Configure -> Message Templates''. This functionality allow you to send a different receipt message based on various criteria, whatever they may be.  You can use any, all or none of a few variable tokens in the templates.  They are pretty much self-explanatory and they are these:
Line 87: Line 110:
 
**%{last_name}
 
**%{last_name}
  
*'''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): <code>?return=http%3A%2F%2Froflcon.org%2Fthanks</code>
+
*'''final_receipt''' (optional): This is the database ID of the message template to use when generating a receipt email to the contributor when the contribution represents the final payment of a subscription.  Note, this field is ''only'' relevant for subscription ("recurring") payments.  If the contribution is a subscription and this is not set ''and'' '''receipt''' is set, then '''receipt''' will be used.  For the set up of this refer to the general instructions above for '''receipt'''.
**'''size''' (optional): If the '''premium''' includes a t-shirt, this is a free-text description of the sizeThis option is ignored if '''premium''' is not set.  Example (urlencoded): <code>?size=Adult+Large</code>
+
 
 +
*'''return''' (optional): This is the URL the contributor will be directed to if/when they click on some link directing them back to your site after having completed the transaction.  Will always have a predefined default value should it not be passed. Example (urlencoded): <code>?return=http%3A%2F%2Froflcon.org%2Fthanks</code>
 +
 
 +
*'''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 account every month for 12 months.  A passed value of 2 means that the '''amount''' will be charged to the contributor's account every month indefinitely.  Example: <code>?recur=1</code>
 +
 
 +
*'''sloptout''' (optional):  This is a Creative Commons-specific field.  You can ignore it.  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 matterIf this variable is not passed, the contributor's name will by default be displayed in public supporter listings.  Example: <code>?slopout=LOL</code>
 +
 
 +
*'''source''' (optional): When the contributor is sent to the payment processor 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.  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 passedWill always have a predefined default value should it not be passed. Example (urlencoded): <code>?source=CC+Network+Annual+Membership</code>
 +
 
 +
=== Sweeping up with ContributionProcessor.php ===
  
*'''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: <code>?recur=1</code>
+
The OneClick system relies 100% on the successful processing of IPN/notifications from the payment processor.  This should normally be nearly 100% reliable, but if for some unforeseen reason it fails, then one can always use the CiviCRM script ''bin/ContributionProcessor.php'' to pull down contributions from the payment processor and record them in CiviCRM.
  
*'''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: <code>?slopout=LOL</code>
+
You could, for example, run ''ContributionProcessor.php'' once a day, or once a week, just to be sure, though it probably isn't necessary. If you choose to run ''bin/ContributionProcessor.php'' periodically to pull new contributions into CiviCRM, your crontab entry will probably look something like:
  
*'''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): <code>?source=CC+Network+Annual+Membership</code>
+
<pre>
 +
*/15 * * * * wget -O - -q -t 1 "https://support.creativecommons.org/sites \
 +
/default/modules/civicrm/bin/ContributionProcessor.php?name=my_user& \
 +
pass=my_pass&key=XXXXXXXXXXXXXXXXXXXXXXXX&ppID=5&ppMode=live&type=paypal" &> \
 +
/dev/null; wget -O - -q -t 1 "https://support.creativecommons.org/sites/default \
 +
/modules/civicrm/bin/ContributionProcessor.php?name=my_user&pass=my_pass& \
 +
key=XXXXXXXXXXXXXXXXXXXXXXXXX&ppID=7&ppMode=live&type=google" &> /dev/null
 +
</pre>

Latest revision as of 19:30, 23 July 2012

Summary

Creative Commons has developed a modified donation process using CiviCRM which can potentially send a contributor off to the payment processor with as little as a single click. All of the donation buttons on CC's donation page utilize this process.

There are a number of possible benefits to using this method as opposed to regular contribution pages in CiviCRM:

  • The contributor (potentially) makes a single click to donate on your site. The less clicks/keystrokes the better chance someone will complete a contribution. I believe this has been empirically tested and demonstrated (??).
  • You are no longer limited to designing your contribution pages within the confines/scope of Drupal and CiviCRM. You can create pages the way you want, wherever you want. This is especially nice for widgets, or anyone else wanting to help your campaign. Potentially, people can create their own donate links on their own sites ... it doesn't matter. And if you run multiple sites, you can place Donate links wherever you want on any of those sites, and it makes no difference whether it's run by Drupal, Wordpress, Joomla, or even made with static HTML.
  • Tired of Pending (Incomplete Transaction) contribution statuses and bogus contacts for people who never completed a transaction? This method virtually eliminates those because a contact/contribution is not created in the CiviCRM database until an IPN/notification is received from the payment processor.
  • As long as the "one-click" scripts are in place, the state of your CiviCRM install doesn't really matter from a user perspective, at least as it relates to contributions. This has been useful for CC when upgrading -- not having to worry about disrupting live contributions should an upgrade encounter problems.

The system is currently comprised of two files: a class file which contains all the code, and a simple router/wrapper script which receives and routes incoming requests:

Special Considerations

This method is known to work with CiviCRM versions 2.2.7, 3.1.1, 3.1.3, 3.1.6 and 3.3.5. It should work fine with any version in the 2.2.x or 3.1.x line.

It currently works with PayPal and Google Checkout.

Configuring CiviCRM for use with OneClick

The OneClick system may require you to make a few configurations in CiviCRM, depending on your needs and how you plan to use OneClick.

  • General: these things should be done no matter what:
    • Administer -> Customize -> Custom Data: here we create a custom data field that is somewhat for internal use but is required for email receipts to work with Google Checkout, but could be useful for future reference or debugging. Create a 'New Group of Custom Fields' Used For - Contributions of Type - Donation. The Group Name doesn't matter. Now add a new Custom Field to the group with these attributes:
      • Field Label (*exactly*): 'OneClick Custom Data'
      • Data and Input Field Type: Alphanumeric - Text
      • Database field length (arbitrarily large): 2000
  • Email receipts: if you'd like to automatically send your donors a receipt by email, then you'll need to do these things:
    • Administer -> Configure -> FROM Email Addresses: add a new FROM address and the Description field must be *exactly*: 'OneClick Email Receipts'. This is the address the receipt will appear to come from. The address will also be Bcc'd on the receipt, and will also be the Reply-To address.
    • Administer -> Configure -> Message Templates: create a new template. This will be the body of the receipt email, and the Message Subject of the template will become the email Subject:. Note the database ID of the template, because you will need to pass this into the system at some point (see Usage -> receipt below).
  • Google Checkout: if you plan to utilize Google Checkout, then you need to do these things:
    • Administer -> Configure -> Global Settings -> Payment Processors: create a new payment processor of type 'Google Checkout and the Name field must be *exactly*: 'Google Checkout API Access'. Fill in the rest of the fields as necessary.
    • Login to your Google Checkout merchant account and go to Settings -> Integration and set the API callback URL to: https://<yourdomain>/sites/default/modules/civicrm/bin/OneClick.php?oc_action=googleipn
  • Optional:
    • Administer -> Customize -> Custom Data: here we create a custom data field that can be used to determine whether a user wants their name to appear in a list of recent donors on your site. NOTE: by itself this field will do nothing for you. It is simply a flag against which you can write your own code to display, or not, your donor names on your site. Use the same custom data group from General above. Now add a new Custom Field to the group with these attributes:
      • Field Label (*exactly*): 'OneClick Supporter List'
      • Data and Input Field Type: Alphanumeric - Text
      • Database field length: 256

Variables

All of the following are found and set in the file bin/OneClick.class.php. There are a few more variables, but the following are the only ones you should change unless you know what you're doing.


// Turn IPN debuggin on/off.  Logs to CiviCRM's default log file.
const OC_DEBUG = TRUE;

// Valid groups that users can join.  This is just a safeguard to prevent
// users from joining arbitrary groups
public $_valid_groups = array(
    'CC Newsletter',
    'CC Events'
);

// IPN callback URL for PayPal
$_paypal_notify_url = 'https://$domain/sites/default/modules/civicrm/bin/OneClick.php?oc_action=paypalipn';

// Email address of site's PayPal account
$_paypal_business = 'paypal@creativecommons.org';

// Minimum contribution amount, anything lower will be kicked back.
$_min_amount = '5';
    
// An array of URLs that should be notified when an incoming
// contribution (via IPN) is successfully processed.
$_notify_urls = array(
    'https://creativecommons.net/a/invite/'
);

// Default name of item as contributor sees it and as recorded in CiviCRM.
$_item_name = 'Online Contribution: Support Creative Commons';

// Where contributor goes if they cancel contribution at payment processor
$_cancel_return = 'https://support.creativecommons.org/donate';

// Where user goes when they click "Return to Merchant Site"
$_return = 'https://support.creativecommons.org/thanks';

Usage

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

  • oc_action (required): The value of this should always be 'donate'. The only other valid values are ones sent by the payment processor. Example: ?oc_action=donate
  • pp (required): The payment processor to use. Presently it can be one of paypal and gc (for Google Checkout). Example: ?pp=paypal
  • 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 a Cancel link on the payment processor's 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. OneClick will not let users join arbitrary groups. Passed groups that are not in the predefined groups list in $_valid_groups 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
    • 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
  • receipt (optional): This is the database ID of the message template to use when generating a receipt email to the contributor. These are the message templates found in CiviCRM at CiviCRM -> Administer CiviCRM -> Configure -> Message Templates. This functionality allow you to send a different receipt message based on various criteria, whatever they may be. You can use any, all or none of a few variable tokens in the templates. They are pretty much self-explanatory and they are these:
    • %{amount}
    • %{date}
    • %{trxn_id}
    • %{first_name}
    • %{last_name}
  • final_receipt (optional): This is the database ID of the message template to use when generating a receipt email to the contributor when the contribution represents the final payment of a subscription. Note, this field is only relevant for subscription ("recurring") payments. If the contribution is a subscription and this is not set and receipt is set, then receipt will be used. For the set up of this refer to the general instructions above for receipt.
  • return (optional): This is the URL the contributor will be directed to if/when they click on some link directing them back to your 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
  • 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 account every month for 12 months. A passed value of 2 means that the amount will be charged to the contributor's account every month indefinitely. Example: ?recur=1
  • sloptout (optional): This is a Creative Commons-specific field. You can ignore it. 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 the payment processor 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. 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

Sweeping up with ContributionProcessor.php

The OneClick system relies 100% on the successful processing of IPN/notifications from the payment processor. This should normally be nearly 100% reliable, but if for some unforeseen reason it fails, then one can always use the CiviCRM script bin/ContributionProcessor.php to pull down contributions from the payment processor and record them in CiviCRM.

You could, for example, run ContributionProcessor.php once a day, or once a week, just to be sure, though it probably isn't necessary. If you choose to run bin/ContributionProcessor.php periodically to pull new contributions into CiviCRM, your crontab entry will probably look something like:

*/15 * * * * wget -O - -q -t 1 "https://support.creativecommons.org/sites \
/default/modules/civicrm/bin/ContributionProcessor.php?name=my_user& \
pass=my_pass&key=XXXXXXXXXXXXXXXXXXXXXXXX&ppID=5&ppMode=live&type=paypal" &> \
/dev/null; wget -O - -q -t 1 "https://support.creativecommons.org/sites/default \
/modules/civicrm/bin/ContributionProcessor.php?name=my_user&pass=my_pass& \
key=XXXXXXXXXXXXXXXXXXXXXXXXX&ppID=7&ppMode=live&type=google" &> /dev/null