Akvo PayPal integration overview
From Akvo Labs
Contents |
Introduction
Architecture
Akvo RSR allows individuals to donate to projects using PayPal. Currently, we implement PayPal Payments Standard, which redirects the user to the PayPal website to confirm their payment. PayPal then send the user an email confirming their donation and send Akvo an Instant Payment Notification (IPN) allowing us to wrap up the transaction and update our database with various bits of data, finally presenting the user with a thank you message, confirmation of the details of their transaction and a thank you email. The RSR PayPal donation subsystem relies on John Boxall's django-paypal application.
Invoices and IPNs
The PayPal subsystem is represented in the Akvo RSR admin interface by two different models: PayPal Invoices and PayPal IPNs. This is potentially confusing and merits explanation.
- PayPal Invoices represent the Akvo side of the transaction. Invoices are created by RSR for the purposes of allowing Akvo to instantiate, track and manage donations.
- PayPal IPNs, on the other hand, represent PayPal. An IPN, or Instant Payment Notification, is essentially a confirmation callback from PayPal which RSR receives when a donation has been completed (successfully or not). The IPN contains, amongst other things, information about the charges PayPal applied. IPNs are not designed to be edited or manipulated directly in the admin interface. They are there more for logging and informational purposes. It is possible, however, that they may be used in future releases to provide, for example, statistical information in the website front end.
Installation and Configuration
Installing django-paypal
Akvo RSR requires that django-paypal be installed somewhere on the system PYTHONPATH. Information on how to install django-paypal can be found on its project page on github. http://github.com/johnboxall/django-paypal/tree/master Checkout the django-paypal source as follows:
$ git clone git://github.com/johnboxall/django-paypal.git
Akvo RSR implements PayPal Standard Payments, so link the standard directory into the system PYTHONPATH. For example:
$ cd /usr/local/lib/python2.5/site-packages/ $ sudo ln -s /path/to/django-paypal/standard paypal
Verify that you can import the paypal module:
$ python >>> import paypal >>>
Configuring Akvo RSR
With django-paypal installed, Akvo RSR's PayPal engine can be configured using several environment variables in settings.py. These environment variables all start with the string "PAYPAL_". Many of them already have sensible defaults. The order of these variables is not significant.
PAYPAL_DEBUG = True # Set to False in production PAYPAL_COMMAND = '_donations' # This defaults to '_donations' PAYPAL_SANDBOX_BUSINESS = 'paul.b_1236803589_biz@gmail.com' # Account used for testing PAYPAL_PRODUCT_DESCRIPTION_PREFIX = 'Akvo Project Donation: ' PAYPAL_SANDBOX_PRODUCT_DESCRIPTION_PREFIX = 'TEST %s' % PAYPAL_PRODUCT_DESCRIPTION_PREFIX PAYPAL_NOTIFY_URL = 'http://%s/rsr/ipn/' % DOMAIN_NAME PAYPAL_RETURN_URL = 'http://%s/rsr/ipn/thanks/' % DOMAIN_NAME PAYPAL_CANCEL_URL = 'http://%s/' % DOMAIN_NAME PAYPAL_IMAGE = 'http://%s/rsr/media/img/paypal_donate.gif' % DOMAIN_NAME PAYPAL_SANDBOX_IMAGE = 'http://%s/rsr/media/img/paypal_donate.gif' % DOMAIN_NAME PAYPAL_RECEIVER_EMAIL = # This is required to exist but is set dynamically by the donation view PAYPAL_INVOICE_TIMEOUT = 60 # integer value in minutes (defaults to 60)
Recent builds of django-paypal have incorporated some of the configuration idioms used in Akvo RSR but with slightly different naming conventions. It is likely, in future releases of Akvo RSR, that the django-paypal naming conventions will be used.
Invoice Management
Overview
Akvo RSR >= 0.9.8 (Utah) includes a python maintenance script which is intended to be run from the system cron daemon. This script goes through the database looking for PayPal invoices which have been pending for longer than a given, configurable period of time. By default, invoices are considered to be stale after 60 minutes (1 hour)
Configuration
Activating this script involves two steps:
STEP 1: Define the environment variable PAYPAL_INVOICE_TIMEOUT in settings.py. This variable defines the period of time, in minutes, after which your site considers an invoice to be stale.
PAYPAL_INVOICE_TIMEOUT = 30
The above example implies that any invoices which have been pending for longer than 30 minutes will be marked as stale. Note that the value of PAYPAL_INVOICE_TIMEOUT is expressed as an integer, not a string. If no PAYPAL_INVOICE_TIMEOUT is specified in settings.py, the system will fall back to the default value of 60 minutes (1 hour).
STEP 2: Decide how often you want to check the database for stale invoices and write a crontab entry accordingly. For example, if you wish to run the script every 15 minutes, add the following to the root crontab:
*/15 * * * * /path/to/akvo/scripts/find_stale_invoices.py
The find_stale_invoices.py script can also be run manually from the command line::
$ cd /path/to/akvo/scripts/ $ python find_stale_invoices.py Finding stale invoices... No stale invoices found.
Whether run from cron or manually from the command line, it will use syslog to add an entry to the system log to indicate how many invoices, if any, were identified and operated on. Here are some example log entries:
Jun 24 08:45:01 my-server python: AKVO RSR PAYPAL: Invoice 54 status changed (pending -> stale) Jun 24 13:00:01 my-server python: AKVO RSR PAYPAL: No stale invoices found.
