In order to integrate with PayPal, you will need to have a PayPal merchant account set up. We are able to integrate via:
- Payments Pro – this allows you to process credit and debit card payments directly through your donation pages, just like any other Gateway
- Express Checkout API – this allows your supporters to donate by logging into their own PayPal account after form submission, via a temporary redirect. This can be combined with another gateway so you can accept card payments and PayPal on the same page
The card types accepted through the Payments Pro gateway depend on the country the merchant account is set up in:
Visa (including Visa Electron and Visa Debit)
Before setting up
Before creating PayPal donation pages, you will need to have at least set up a test merchant account with PayPal, and you will need your own live PayPal merchant account to accept real donations. You will also need to decide what base URL you would like to use for your donation pages, and ensure that a certificate exists for it on our load balancer.
You will need to obtain your Paypal API credentials in order to link Engaging Networks donation pages to your PayPal account. You should be able to obtain these from the ‘profile’ tab in your PayPal interface. You will require an API username, password and signature. Note that the API username and password differ from the username and password used to log in to your PayPal merchant interface.
It is also a good idea to create a test merchant account and test buyer accounts using PayPal’s sandbox environment, so that you can test your pages before going live. Details of how to do this are on page 3 of this document.
Setting up the paypal gateway
The Gateway information is defined in the fundraising section, under Hello YOURNAME > Account settings > Gateways. If you select “Paypal” from the dropdown, you will be asked to supply the following information:
|Reference name||A unique name for the gateway. It is a good idea for the name to include the type of gateway (eg. Paypal account), and whether it is a live or test gateway.|
|Select gateway||Select ‘Paypal Gateway’.|
|Username||Enter your PayPal API username. This differs from your normal PayPal login username, and can be obtained from the API credentials section of your PayPal profile.|
|Password||Enter your PayPal API password. This differs from your normal PayPal login password, and can be obtained from the API credentials section of your PayPal profile.|
|Signature||Enter your PayPal API signature. This can be obtained from the API credentials section of your PayPal profile.|
|Test mode||Should be checked for a test gateway, must be unchecked for a gateway that will accept live donations.|
|Enable 3D||You can tick this if you need to integrate the gateway with PSD2|
Required form fields
The following fields need to be set up in the default supporter record and then added to the form in ‘build’.
Basic required fields:
|Form Field||Value type||Comments|
|Email Address||Alphanumeric||Email address identifying the supporter record|
For card payment methods, one of the following values should be passed in (case insensitive):
Pay via paypal
For this, use PayPal (again case insensitive). This will invoke a redirect to the Paypal login page once the buyer submits the donation page. Once they have completed the transaction they will be redirected back to the Engaging Networks thank you page as set up for your donation page.
NOTE: ‘Paypal’ can be included in the same drop-down as card payment types, but card details entered will be ignored because the supporter is being sent to their paypal account. See the section on “dependencies” for how to hide the card form fields if PayPal is selected
Pass in the currency of the transaction. The currencies your PayPal account can accept are defined at set up. Get in touch with your contact at Paypal if you need to confirm which currencies are allowed.
The value passed in must be in three-letter ISO-4217 format, eg. GBP for pounds sterling. A list of acceptable codes may be found here.
NOTE: If you are only accepting a single currency, you must still have this on the page in design. However there is no need to display the field to supporters. It can be marked as not visible when setting up your form.
|Donation Amount||Numeric||May be entered as a whole number, or with two decimal places. Eg. Twelve dollars may be entered as ’12’ or ‘12.00’. You may want to consider using the ‘select with input’ or ‘radio with input’ field types ‚Äì see below.|
Additional fields required for card payments
Not required for “pay via paypal”.
|Form Field||Value type||Description|
|Credit Card Number||Integer||Credit card number w/o spaces|
|Credit Card Expiration||Date||Format must be MMYYYY. It is strongly recommended that you use the ‘split select’ field type for this form field. See below for details.|
Credit Card Verification value
(CVV2 or CVC2)
|Numeric||The additional Card Verification Value printed on the card, used for fraud checks.|
|First Name||Alphanumeric||The card holder’s first name|
|Last Name||Alphanumeric||The card holder’s last name|
|Address 1||Alphanumeric||The address of the cardholder|
|City||Alpha||The address of the cardholder|
|ZIP/postcode/postal code||Alphanumeric||The postcode of the cardholder|
The cardholder’s country must be submitted in upper case two-letter ISO-3166 format, which can be found here.
Please see the notes below on ‘select’ field types for details of ways of presenting these fields to supporters.
Credit card number and credit card verification values are not stored in the default supporter record.
Additional Fields for Recurring Payments
|Recurring Payment||Alpha||Submitting ‘Y’ will flag the transaction as a recurring payment. Any other value will result in a single payment.|
|Recurring Frequency||Alpha||Permitted values are MONTHLY, QUARTERLY, SEMI_ANNUAL and ANNUAL. Please see the notes below on ‘select’ field types for details of ways of presenting these fields to supporters.|
|Recurring Day||Numeric||The day of the month on which the recurring payment should be taken.|
|Recurring End Date (optional)||Numeric||When this recurring payment should cease. The value must be in the format DD/MM/YY|
Required fields for Recurring Paypal Payments
|Billing Agreement||Alpha||Must submit text confirming that the donor agrees to the recurring paypal payment. Recommend field type = ‘text-uneditable’|
For more information about recurring paypal processing click here.
Additional PayPal Settings
Clients need to set the notification URL to our callback URL, which internally calls PayPal to check the status of the transaction. Here are the steps to take in order to have these changes apply to your Engaging Networks platform.
Testing donation pages using the PayPal Sandbox
PayPal provide a ‘Sandbox’ environment that allows you to create both test merchant and test buyer accounts, that you can use to try out your page before making live.
The Sandbox can be accessed at developer.paypal.com. First you will need to login with your paypal account. Then select “applications” and “sandbox accounts”. You will be presented with a list of your sandbox accounts. Create a new account, filling in a valid email (that is not already in use for your paypal account), first name, last name, country and a password.
Choose “business”, as we are creating a sandbox merchant account, not a buyer account. Credit credit type refers to the test card details that will be created automatically for this sandbox merchant.
Once you submit this form, your new sandbox account will appear on the list. Select the black arrow dropdown next to it and click “profile”.
The API credentials tab contains the details you will need to set up a test gateway in engaging networks. (see section 1).
The funding tab contains your test card details for use with this sandbox account.