Last updated January 2018
To get started, you need access to both your NationBuilder and PayPal accounts. If you don’t have an existing PayPal account, create a free business account from their website.
Once you create an account, you must generate API credentials in order for PayPal to identify your specific PayPal account.
Table of Contents
- Get your API credentials from PayPal
- Connect with PayPal
- Configure instant payment notifications (IPN)
- Manage recurring donations in PayPal
- Related HOWTOs
- Issues and suggestions on our radar
Get your API credentials from PayPal
In order to connect your PayPal account with NationBuilder, you have to create an API signature. For this you'll want to log in to your PayPal business account and follow the steps illustrated below.
To access the API credentials setup, you'll want to click on the Tools tab in the top navigation bar and select All Tools.
- Scroll down to find "API credentials" tile and click Open.
- When you land on the API access page, go to the NVP/SOAP API integration section and select Manage API credentials.
Note: If you've already generated an API signature, a “View API signature” link is displayed on the API access page. If you need to generate a new API signature, you must delete the existing one if it is not being used by a live application. Do this by clicking on the “View API signature” link and selecting the Remove button to delete the existing signature.
- From the Request API credentials page illustrated above, select “Request API signature” and click Agree and Submit, and the API signature credential will be generated like below:
Keep the API username, password, and signature in hand in order to connect NationBuilder with PayPal.
Learn more about creating PayPal API credentials.
Connect with PayPal
Once you have your PayPal username, password, and signature, access your NationBuilder control panel. Go to Settings > Payment processors > New processor and select PayPal Express from the "Select provider" dropdown under "Third-party processor." Click the Add payment processor button.
On the New processor page:
- Enter a name.
- Get your PayPal API username, password, and signature. Copy each from PayPal and paste it into the required “API username,” “API password,” and “Signature” fields.
- You have the option to choose a description for your organization through the “Type of organization” dropdown menu. The different options include for profit, nonprofit, charity, individual, federal_candidate, federal_pac, federal_party, state_candidate, state_pac, state_party, local_candidate, local_pac, and local_party.
- If you want your PayPal account to be in test mode, check off “Testing mode” and make sure that you are using your API test credentials and not your live credentials.
Note: In order to get test credentials, you or your developer must have PayPal sandbox test accounts. If you check off “Testing mode” and try to save the account while using your live credentials, you will get an error message.
Choose how donors will interact with your donation page. First, decide whether the donations are tax deductible. This status will appear on the donation page and on donation receipts.
You may require a donor’s employer and occupation, the employer’s full address, or just the employer’s city and state. You may also include corporate contribution fields. If you are a political campaign, check your local and Federal regulations to see if you are required to collect this information. Activate any setting by checking the appropriate text box.
- If your organization has a specific disclaimer or contribution rules required to accept donations, enter that copy in the "Contribution rules" text box. This includes specific disclaimers mandated by campaign finance law. Donors will have to check a box accepting these statements before submitting a donation.
- Once you’re done filling out the form, click the button. A donation page that is connected to this payment processor will pull from these fields.
- You’ll see your newly added payment processor in Settings > Payment processors > All processors.
Configure instant payment notifications (IPN)
NationBuilder will only be able to provide you with real-time donation information if you configure your Paypal account to send instant payment notifications (IPN) to your nation. These notifications come in handy when you want to properly track recurring donations in PayPal.
When you first connect a PayPal account with your nation, you will automatically be redirected to the “Instant payment notification configuration” page. You can follow the instructions on the page to configure IPN from PayPal and then select the IPN Configured button or choose to do the configuration at a later time.
Note: If you decide to do the configuration at a later time and need to go back to the IPN configuration page, go to Settings > Payment processors > All processors > Select pencil button next to Paypal account. At the top of the Paypal account page, select Click here from the notification and get redirect to the IPN configuration page.
Below are more detailed instructions on how to configure IPN:
- Sign in to your Paypal account.
- Click on the Profile icon in the top right-hand corner and select Profile.
- Select My selling tools from the left menu.
- In the “Getting paid and managing my risk” section, find “Instant payment notifications” and click on the Update link.
5. Select the Choose IPN Settings button.
6. On the “Edit instant payment notification (IPN) settings” page, you will have to enter the notification URL. To receive the notification URL from NationBuilder, go to the “Instant payment notification configuration” page on NationBuilder and copy the generated URL from step 6.
7. On Paypal, select the “Receive IPN messages (Enabled)” radio and click the Save button.
Once you save, remember to go back to the Instant payment notification configuration page on NationBuilder and click the IPN Configured button.
Manage recurring donations in PayPal
PayPal is a payment processor that supports monthly donations. It can also be used to process installment payments. If you use PayPal Express Checkout you must have a business account.
Note: When using PayPal Express Checkout, the donor will complete the transaction on the PayPal website. Donors will have to log into their own PayPal account or create a new PayPal account to complete the transaction.
After you connect PayPal to your donation page and enable installment payments or monthly payments, you will be able to manage all recurring payments in your PayPal account. To keep track of real-time recurring donations processed in PayPal, configure your account to accept instant payment notifications (IPN).
Log in to your PayPal business account and click on the Profile icon in the top right-hand corner and select Profile.
- Select My selling tools from the left menu.
In the “Getting paid and managing my risk” section, find “My automatic payments” and click on the Update link.
Note: PayPal refers to recurring donations as “subscriptions.” You will land on the recurring payments dashboard where you can manage recurring donations and installment plan payments.
Issues and suggestions on our radar
There are some issues related to the integration with PayPal that have come to our attention. We are monitoring their importance to the community on the product issues and suggestions page. You can follow each of the below issues to keep updated on their status.