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

Instructions for setting up PayPal OneTouch can be found here.

The card types accepted through the Payments Pro gateway depend on the country the merchant account is set up in:

Country

Cards Accepted

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.

Obtaining PayPal API Credentials
PayPal > Name (upper right hand corner) > Account Settings > API Access > Update > NVP/SOAP API Integration > Manage API Credentials > Request API Signature > Agree  & Submit > click show to view credentials.

It is recommended to create 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

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

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.

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

Form Field

Value type

Description

Credit Card Number

Token

Credit card number without 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)

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

The cardholder’s country must be submitted in upper case two-letter ISO-3166 format, which can be found here.

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

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.