The Worldpay Gateway

Worldpay is one of the payment gateways you can use in Engaging Networks to process donations and payments. 

This document contains details for setting up the Worldpay gateway in Engaging Networks.

We can integrate with two types of Worldpay gateway:

  1. Worldpay Corporate gateway (formerly known as the Global Gateway). This can process recurring card payments. You will also need to enable IP addresses for the integration to work – see below

  2. Worldpay Business gateway. This cannot process recurring card payments. You will need to also have an Installation ID for this to work – see below

Before setting up the gateway

1) Arrange a merchant account with Worldpay

Before creating Worldpay donation pages, you will need to have arranged your merchant account with Worldpay. We recommend having a Live and a Test version. 

2) Ensure you have a Base URL for donation pages

If you haven’t already got a Base URL (subdomain) for your donation pages, please contact the Support team. This needs to be entered into the Account Preferences’ “Donation Base URL” which can be accessed via the Hello > Account settings > Account preferences menu. 

3) Tell WorldPay to enable “Invisible XML” on your account

Invisible XML needs to be enabled before our integration can work. Contact Worldpay Support to set this up.

4) Enable IP addresses [Corporate Gateway accounts only]

In addition, you will need to log into your merchant account using the Worldpay interface and enable the IP addresses for both the Test and Live versions of the gateway (this applies to Corporate Gateway accounts only):

3.19.5.96 3.140.123.11 3.97.146.169 15.222.229.212 3.138.251.155 3.22.198.235

5) Find the Worldpay credentials needed to set up the gateway in Engaging Networks

You will need the following credentials in order to link to your gateway. You can find these from within your Worldpay dashboard:

  • Worldpay merchant code

  • XML password

  • Installation ID [Business gateway only]

The XML password differs from the password you use to log into your merchant account.

For clients in the UK or Europe, or those that wish to take donations from supporters in those locations, you will also need to get additional credentials to set up 3DS2 which enables an additional authorisation step to display so that the supporter can securely authorise their donation, for example via a code sent to their mobile device.

Contact your Worldpay representative and ask them to provide you with these Cardinal Commerce credentials to set up 3DS Flex (Direct):

  • API Key

  • API Key ID

  • Org Unit ID

Setting up the Worldpay gateway in Engaging Networks

It is recommended that you create and keep two separate gateway records in your account, one for testing and one linked to your live gateway. Donation pages should be linked to a test gateway initially, and then switched to a live gateway before launch. To create each one:

  1. Go to Hello YOURNAME > Account Settings > Gateways

  2. Click New Payment Gateway to create a new entry

  3. Add information to the fields:

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. Worldpay corporate gateway), the currency (if applicable), and whether it is a live or test gateway.

Select gateway

Choose “Worldpay”

Username

Enter your Worldpay Merchant Code in capital letters

XML Password

Enter your XML password

The XML password is set in the merchant gateway, it is not the password to log into your merchant account. The two passwords are different.

Installation ID

[Corporate Gateway only]. Enter your Installation ID here. Leave blank for the Business Gateway

Enable 3D

Tick this if you want to use 3DS2 which is needed for supporters in the UK and Europe. This will enable an additional three fields.

API Key

[Enable 3D only]. Add the API Key given to you by Worldpay.

API Key ID

[Enable 3D only]. Add the API Key ID given to you by Worldpay.

Org Unit ID

[Enable 3D only]. Add the Org Unit ID given to you by Worldpay.

Test gateway

Should be checked for a test gateway, must be unchecked for a gateway that will accept live donations.

  1. Save the gateway. Repeat so you have one Gateway for Live payments, and one for Test

Anyone within the merchant’s organization who has access to the merchant interface can change the xml password. WorldPay does not have access to the merchant’s passwords and can only assign new passwords, rendering the current password inoperable.

Enabling fields to take donations using the Worldpay gateway in Engaging Networks

The following fields need to be set up in the Account Data Structure and then added to a form block in your page using page-builder. 

You may already have some of these fields in your account, in which case you need not add them.

Basic required fields for credit/debit card single payments

Field

Default input type

Comments

Field

Default input type

Comments

Email Address

Text

Email address identifying the supporter record

Credit Card Holder
Name

Text

Card holder name exactly on card

Credit Card Number

Token

Credit card number w/o spaces

Payment Type

Select

If the page is configured to only accept credit cards this is optional.

Credit cards = CreditCard (the specific type will be detected on the form and captured with the transaction )

Payment Currency

Select for multiple currencies, or Hidden for a single currency

This will contain the three letter ISO-4217 currency code, eg. GBP for pounds sterling.

N.B. If you are only accepting a single currency, you must still have this on the page in your form block, but there is no need to display the field to supporters. It can be set as a “Hidden” field.

Credit Card
Expiration

Split select

Format must be MM/YYYY. It is recommended that you use the ‘split select’ field type, so that one field holds the month (01 to 12) and the other the year (2022 onwards).

In page-builder, it should have a delimiter of /. 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.

Donation Amount

Text if you don’t want to give options.

Radio with input for set amounts & an Other option.

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.

Additional fields required for Worldpay Corporate Gateway recurring payments

A recurring payment page is built in exactly the same way as a single payment pages, but with the addition of several fields specific to recurring payments:

We can only process recurring payments for the Worldpay Corporate Gateway (formerly known as the Global Gateway), not the Business Gateway. The initial payment is processed in the same way as a single payment, and then subsequent payments are requested automatically by Engaging Networks at the defined interval. You can manage recurring payments via the ‘Manage Supporters’ page in the client dashboard.

Field Name & Field Tag

Default input type

Description

Field Name & Field Tag

Default input type

Description

Recurring Payment

Radio or Select

Submitting “Y” will flag the transaction as a recurring payment. Any other value, e.g. “N”, will result in a single payment.

You can set this up as a radio with labels of “Recurring” and “One-off” with values of “Y” and “N” respectively.

Recurring Frequency

Radio or Select

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.

If you only wanted to take monthly payments, you could set this up as a Hidden field with a default value of MONTHLY in page-builder.

Recurring Day

Hidden or Select

The day of the month on which the recurring payment should be taken. If left blank as a Hidden field, this will use today’s day so that subsequent payments are taken on the same day as the initial payment every month.

Recurring End Date (optional)

Numeric

When this recurring payment should cease. The value must be in the format DD/MM/YY

Other optional fields you may want to include

It is strongly recommended you include name and address fields on your donation page for added fraud protection, since Worldpay can use these to match the card details and determine whether the donation is valid.

Field Name & Field Tag

Default input type

Description

Field Name & Field Tag

Default input type

Description

Issue number

Text

This field must be displayed if you are potentially accepting donations from debit cards, but should not be made mandatory as not all debit cards have an issue number. It is possible to use ‘form dependencies’ to dynamically hide or show this field depending on the card type selected. Please contact us for help setting up this feature.

First name and last name

Text

The supporter’s first/last name (as opposed to cardholder name)

Address 1

Alphanumeric

The street address of the cardholder. If this field is submitted, both postal code and country must also be submitted.

Postal code

Alphanumeric

The postcode of the cardholder. If this field is submitted, both address 1 and country must also be submitted.

Country

Alpha

The cardholder’s country. This must be submitted in upper case two-letter ISO-3166 format (for example “GB” for the United Kingdom). If this field is submitted, both postal code and address 1 must also be submitted.

Testing donation pages

Provided that you are using a gateway set up in test mode, you can use the following card details during the testing process. All other form fields may take any value, as long as expiry date is set to some time in the future.

Card scheme

Card numbers

Card scheme

Card numbers

Maestro

6759649826438453 (this card has no issue number but uses a start date)

Visa

4111111111111111
4444333322221111

Amex

34343434343434

Ecmc

5555555555554444
5454545454545454

Diners

36148900647913

Dankort

5019717010103742

Airplus

122000000000003
192000000000008

Laser

630490017740292441

Cb/Cartebleue

5555555555554444

You can check orders after submitting the test transaction by logging into your merchant account with Worldpay and switching to the test environment.