The Paypal Gateway
- Michael Kalnicki
- Sam Louk
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
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 |
|---|---|
Canada | Visa |
United Kingdom | Visa (including Visa Electron and Visa Debit) |
United States | Visa |
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 |
|---|---|
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 ) 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 |
|---|---|---|
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 |
|---|---|---|
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.