|Scope and Audience|
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...).
|Availability May Be Limited for Organizations Outside of the United States|
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:
- PHP Perl Compatible Regular Expressions extension for PHP 4.3.0+ and higher
- PHP cURL extension for PHP 4.3.0+ and higher with SSL support
- PHP OpenSSL extension for PHP 4.3.0+ and higher (for digital certificate transcoding)
- As of Aug 20, 2007 - The version of PayPal Payments Pro API used by CiviCRM 1.9 and below is apparently not compatible with PHP 5.2.3+. If you are running 5.2.3+, you will need to upgrade to CiviCRM 2.0 which uses the newer PayPal API and IS compatible with PHP 5.2.x+.
Use phpInfo() to check for these extensions. You should see the following lines:
Create a Developer Central Account
- Go to https://developer.paypal.com/devscr?cmd=_signup-run
- Fill out the sign-up form (be sure to make a record of the email address and password used - and use a valid email address so you can respond to the activation email sent by PayPal).
- Check for activation email and click on link to go to Developer Central login page
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.
Bank Account Number:
Any 8-digit number- try to be unique - see Error message for why
609204 or 700709
any random number
Bank Account Number:
Any 10-digit number
Bank Account Number:
Any one-digit to 12-digit number
Any 8-digit number
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
- *- Confirm your bank account by continuing and following instructions on the next screen.
- Click continue on the Congratulations screen. (Ignore the statements about confirming deposits to this dummy account - this only happens for a live account.)
- Click Confirm button on the next page (Confirm your bank account). Then follow Sandbox prompt and click Submit.
- You should see Your Bank Account in the United States Has Been Confirmed
Return to Overview tab in the Sandbox. Your account status should now be *Verified
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
- Login to your Sandbox Account.
- Click the Profile sub-tab from My Account.
- Click the API Access link in the left column (under Account Information)
- Click Request API Credentials from the API Setup page.
- Select the API Signature option, mark the Terms checkbox, and click Submit
- A page with your credential information is displayed. Record the values for:
- API Username
- API Password
- API Signature
|Changing from API Certificate to API Signature|
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:
- 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
- Log into CiviCRM as an administrator.
- Select Administer CiviCRM.
- Select Global Settings.
- Select Enable Components and ensure that CiviContribute is enabled.
- Select Administer CiviCRM >> Global Settings >> Payment Processors
- Click » New Payment Processor
- Select PayPal - Website Payments Pro for Processor Type.
- Complete the fields in the Processor Details for TEST Payments section with the values from your PayPal Sandbox account's View API Signaturescreen:
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.
- Navigate to Drupal administer >> settings or (administer >> site configuration >> error reporting )
- In the Error Handling section, the Error Reporting drop-down should be set to Write errors to log. Update and save this setting if needed.
NOTE: This is the recommended setting for production sites.
If the following warning is displayed after clicking Make Contribution - your Error Reporting setting is incorrect:
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.
- For Contribution Pages - go to Manage Contribution Pages » Configure » Contribution Amounts and select your PayPal Website Pro processor, then click Save.
- For Event Registration - go to Manage Events » Configure » Event Fees and select your PayPal Website Pro processor, then click Save.
Test-drive a CiviContribute Online Contribution Page
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:
- Standard Subscriptions require the contributor/donor to have a Paypal account while Pro Recurring does not require the donor to have a Paypal account. A credit card is sufficient to use Paypal Pro recurrings.
- Standard Subscriptions are included for free in your Standard account services. Pro Recurring feature costs an additional monthly charge on top of Pro.
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:
- Log in to your Paypal account, click "Profile" in the top navigation
- Look to the bottom of the page, click "Instant Payment Notification preferences"
- Enter your URL for your ipn.php page
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
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.
- The 'initial' payment is transacted immediately, in the amount specified
- A separate, 'repeating' (in the case of Pro) or 'subscription' (in the case of Standard) is also created, which will transact again at the specified interval, duration and amount
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.