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.
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.
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
Make a record of this Sandbox Business Account login (email and password). You will need it to login to the Sandbox in the future.
Please make sure that you actually select a domain that matches the one on your test server if you plan to use the recommended Signature Authentication method. While most of the data you input here can be fake, the business website address you enter should match your test server domain as PayPal will encrypt your key using this domain.
UK, Australian, Canadian and German Accounts
To add test Canadian, German, or UK bank account information, use the following test numbers.
Bank Account Number:
Bank Account Number:
Bank Account 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
Click Agree to confirm billing agreement
There is actually no charge for using any of the services in the PayPal Sandbox. However, you will need to go through the same steps if you choose to create a live Website Pro Account. EXCEPT there will be a waiting period while PayPal actually reviews and approves your application.
When going through these steps for a live account, you should see a Getting Started panel in the upper left corner of your My Account - Overview tab. Once you complete Step 2 - Verify your (bank account) information, you should be able to click on Apply for Website Payments Pro to begin the process. After submitting the requested info online - you will need to wait for an approval email reply from PayPal - in our experience this took approximately 3 days.
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.
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:
You can generally accept the default values for Site URL, API URL and Button URL.
CiviCRM allows you to store settings for connecting to both the Test and Live Payment Processor servers. When first setting up your site to accept online contributions, you should configure both TEST and LIVE server settings with test values. This will ensure that no LIVE transactions are submitted unintentionally. Once you have tested your site thoroughly, you can update the LIVE settings with the correct values for your live merchant account. The TEST settings will be used when you access an Online Contribution Page in Test-drive Mode.
Remember that when you are ready to configure CiviContribute for LIVE payments, you must generate new API credentials by logging in to your live merchant account (at http://www.paypal.com. Then, enter these values in the Processor Details for LIVE Payments section of the Payment Processor configuration form. We recommend doing an initial LIVE contribution yourself and then checking for activity by logging back in to your PayPal account.
If you have setup your API Access using the API Certificate method, and want to change to API Signature - you first need to Remove the existing credential. Click View or Remove Credentials from the API Setup page (My Account >> Profile >> API Access). Then click the Remove button. After confirmation, you are redirected to the API Setup page where you can click Request API Credentials to get a new credential.
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.
You must assign your new Payment Processor to your Contribution Page or Event Registration before you can test-drive them.
Click on the referenced 'Test-drive' link for your page and make a contribution. In this mode, contributions records are saved with a Test flag. These are not shown under contact view - but you can view them by searching for Test Contributions under CiviContribute » Find Contributions.
Use the PayPal Sandbox Add a Credit Card function to generate credit card numbers which are valid for testing.
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
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.
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.