The Paypal Gateway

In order to integrate with PayPal, you will need to have a PayPal merchant account set up. We are able to integrate via:

1. Payments Pro – this allows you to process credit and debit card payments directly through your donation pages, just like any other Gateway
2. 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:

Country	Cards Accepted
Canada	Visa Mastercard
United Kingdom	Visa (including Visa Electron and Visa Debit) Mastercard Maestro
United States	Visa Mastercard Discover American Express

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:

Field	Description
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 Account Data Structure 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
Payment Type	Alpha	*This is optional if the page only accepts credit card payment types, but is required if other types like pay via PayPal are accepted on the same form. Credit Cards = CreditCard (the specific type will be detected on the form and captured with the transaction ) Pay via PayPal = PayPal 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. If offering credit cards and PayPal you should use Dependencies to hide the card fields (card name, number, expiry, CVV) if PayPal is selected
Payment Currency	Alpha (Three-letter)	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	Token	Credit card number without spaces
Credit Card Expiration	Date (MMYYYY)	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)	Token	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
Country	Alpha (two-letter)	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

Form Field	Value	Description
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/YYYY

Required fields for Recurring Paypal Payments

Form Field	Value	Description
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.

Enabling PayPal One Touch

Please refer to this article

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.