The Worldpay Gateway

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

We can only process recurring payments for the Worldpay Corporate Gateway (formerly known as the Global Gateway), not the Business Gateway

Before setting up

Before creating Worldpay donation pages, you will need to have arranged your merchant account with Worldpay. 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 also need to tell WorldPay to enable “Invisible XML” on your account.

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

3.19.5.96
3.140.123.11
3.97.146.169
15.222.229.212

Finally, you will need your Worldpay merchant code and xml password in order to link to your gateway.

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

Setting up a gateway

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. The fields are set up as follows:
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 Select  ‘Worldpay’.
Username Enter your Worldpay Merchant Code in capital letters
Password Enter your XML password (This differs from the password you use to log into your Worldpay merchant account.)
Installation Id Corporate Gateway customers should leave this
blank.
Test mode Should be checked for a test gateway, must be unchecked for a gateway that will accept live donations.

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.

Please note that 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.

Form fields

The following fields need to be set up in the default supporter record and then added to the form in ‘build’. 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:

Basic required fields for credit/debit card single payments

Form Field Value Comments
Email Address Alphanumeric Email address identifying the supporter record
Credit Card Holder
Name
Alpha Card holder name exactly on card
Credit Card Number Integer Credit card number w/o spaces
Payment Type Alpha See the payment methods section below. This field is not case sensitive.
Payment Currency Alpha

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 design, but there is no need to display the field to supporters. It can be set as a “Hidden” field, or in the legacy tools marked as not visible when setting up your form.

Credit Card
Expiration
Date Format must be MM/YYYY. It is strongly recommended that you use the ‘split select’ field type for this form field with a delimiter of /. 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.
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.

Credit card number and credit card verification values are not stored in the default record.

Additional fields required for Worldpay Corporate Gateway 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.

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

Other optional fields you may want to include

Form Field Value Description
Issue number Numeric 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 Alpha 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. If this field is submitted, both postal code and address 1 must also be submitted.

Payment methods for Worldpay gateways

In the Payment type field, the following values are accepted (case insensitive):

Recurring and Single payments

  • American Express: american express, americanexpress, amex
  • VISA (incl. Electron): visa
  • Mastercard: mastercard, master card, mc
  • Carte Bancaire: carte bancaire
  • Carte Bleue: carte bleue
  • Diners: diners
  • Laser Card: start with ‘laser’ or contains ‘laser’
  • Discover: discover
  • Japanese Credit Bank: jcb, japanese credit bank, japan credit bank
  • Dankort: dankort

Single payments

  • Maestro: maestro

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
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.

Updated on September 16, 2021

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