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

With Payments Pro, it is possible to accept single and recurring payments through the same donation page, by including the ‘Recurring Payment’ field as a drop-down, radio button or check box.

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 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
Payment Type Alpha

For card payment methods, one of the following values should be passed in (case insensitive):

Visa
MasterCard
Discover
Amex

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.

The value ‘Paypal’ can be included in the same drop-down as card payment types such as Visa and so on, but 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 Integer 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)

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
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/YY

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.

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.

Updated on August 12, 2019

Was this article helpful?

Need Support?
Can’t find the answer you’re looking for? Don’t worry we’re here to help!
Contact Support