This document covers the steps needed to configure and run CiviContribute using the PayPal Website Payments Pro plugin. This plugin supports PayPal Pro Express Checkout, and (if desired) Direct Checkout. Consult the PayPal's site for an overview of features and pricing for Website Payments Pro.
The installation of the PayPal plugin is recommended for developers and technical users only at this stage. It is important that you thoroughly test your site using PayPal Sandbox Server and Sandbox accounts prior to configuring and enabling live transactions. You will also need to acquire and install an SSL certificate if you planning on offering Direct Checkout (more info...).

If your organization is headquartered outside of the United States, we recommend that you confirm availability of Website Payments Pro for your country (and/or banking relationship) with PayPal prior to beginning configuration of this plugin.

PHP Configuration Requirements

The following PHP extensions must be enabled in order for CiviCRM to interface with PayPal's payment services:

Use phpInfo() to check for these extensions. You should see the following lines:

PCRE (Perl Compatible Regular Expressions) Support => enabled
CURL support => enabled
OpenSSL support => enabled

Create a Developer Central Account

Create a Business (Merchant) Account on the PayPal Sandbox

UK, Australian, Canadian and German Accounts
To add test Canadian, German, or UK bank account information, use the following test numbers.

UK

Australia

Canada

Germany

Bank Account Number:
Any 8-digit number- try to be unique - see Error message for why

BSB Number:
242-200

Transit Number:
00001

Routing Number:
37020500

Sort Code:
609204 or 700709

Account Number:
any random number

Institution Number:
311

Bank Account Number:
Any 10-digit number

 

Bank Account Number:
Any one-digit to 12-digit number

Sort Code:
Any 8-digit number

 

Error Messages
If receive an an error message when attempting to verify the account, contact MTS requesting that they verify the  account for you, providing the email address of the Sandbox account.
Contact MTS including your Sandbox Email Address by clicking on https://www.paypal.com/mts. I have an unconfirmed theory that if the account already exists in the system you get the error message which would explain why numbers like 12345678 seem to have failed for me

Enable Website Payments Pro for Your Sandbox Account

Configure API Access

API Credentials are used to authenticate the connection between the PayPal payment gateway and the server where CiviContribute is installed. Two types of credentials are available - API Signature and API Certificate. The API Signature credential is recommended because it is easier to configure.

Generate API Signature Credential

If you previously used an API Certificate with PayPal Pro, you will not be able to generate an API Signature until you delete the API Certificate. The interface for doing so from Canada in May, 2012 is:

  • Login
  • Click the Profile sub-tab from My Account
  • Click Request API Credentials
  • Under Option 1: PayPal API, click Set up PayPal API credentials and permissions
  • Under Option 2 - Request API credentials to create your own API username and password, click View API Certificate
  • Click Remove, then Remove again
  • Then under Option 2 - Request API credentials to create your own API username and password, click Request API credentials
  • Leave the default Request API Signature as your choice for the kind of API credential. Click Agree and Submit.

 

Configure CiviContribute Using API Signature

Configure Drupal Error Reporting

The PayPal SDK currently triggers a PHP warning during transaction processing. This warning does not affect processing - but you need to make sure that Drupal is configured to NOT display warnings on the screen.

If the following warning is displayed after clicking Make Contribution - your Error Reporting setting is incorrect:

warning: Services_PayPal::getType(Services/PayPal/Type/Struct.php)
[CRM:function.getType]: failed to open stream: No such file or directory
in <drupal-root>/modules/civicrm/packages/Services/PayPal.php on line 50.

Assign this Processor to your Contribution or Event Registration Page(s)

You must assign your new Payment Processor to your Contribution Page or Event Registration before you can test-drive them.

Test-drive a CiviContribute Online Contribution Page

Recurring Contributions

As of version 3.1, CiviCRM supports Paypal Pro recurring contributions. Prior versions of CiviCRM do NOT support Pro recurring contributions.

The differences between Paypal Standard Subscriptions and Paypal Pro Recurring Contributions are as follows:

To take advantage of recurring and one-time contributions on the same CiviCRM Contribution page, you must have the Pro Recurring add on.  You cannot process Pro one-time donations and Standard Subscriptions from the same Contribution page.

Once you have added the Recurring feature to your existing Paypal Pro account, configure your IPN settings in Paypal so CiviCRM can recieve updates on the recurring contributions in this manner:

Note: You can re-send an IPN message from this area by using the IPN search. This is good if you have had it set to the wrong URL & want to resend them once you've fixed it

Expected Behavior
When CiviCRM processes a recurring contribution via Paypal (Standard or Pro) a single Contribution is created in CiviCRM which is marked visibly as "recurring". However within the Paypal account history, two separate transactions will be visible.

With Paypal Standard, a payor wishing to stop their recurring payment may do so within their own Paypal account by stopping their subscription. In contrast, with Paypal Pro, the payment is made via credit card and thus the repeating payment must be stopped from within the merchant's Paypal account, not the payor's Paypal account.

Recurring Processing Failure
Credit card numbers and expiration dates change over time. Because neither CiviCRM nor Paypal are capable of reaching into a payor's wallet to update this information, you should expect that a percentage of recurring payments will fail. When this happens, CiviCRM records a contribution of status "Failed" associated with the Contact record, although CiviCRM does not send a "Failed" email notification to the payor directly. Paypal will, however, send an email to the payor notifying them of a failed recurring payment and the repeating payment or subscription will be canceled. The payor can then attempt to re-establish their payment.

Apply for and Configure Your LIVE Account

Once you are comfortable with your site's operation in testing mode, you will need to apply for a live PayPal Business Account here - or upgrade an existing PayPal account to a Business Account. Approval may take several days.

The basic steps for obtaining and configuring your live Profile and settings are the same as for the Sandbox process described above - except that you will request the API Signature from your live merchant account login - and populate the Live settings in the Processor configuration screen.

Once you have your LIVE account configured, it is important that you submit a few live contributions prior to exposing your live online contribution page(s) to the public.