Configuring Your Installation

Facilities for configuring your installation are found on the WorldPay Administration Server (WAS) at URL https://select.worldpay.com/wcc/admin. When you log on you will be presented with a list of all your installations, with a button to take you to configuration options. These include uploading files and setting the options for call-backs and template files.

Managing Files on the WorldPay server

Uploading files

Use the file upload form for the appropriate installation. These files are all placed in a single directory named for your installation id.

Viewing and Deleting Files

Use the file management options on the administration page for the appropriate installation.

Referencing Graphics

Any graphics referenced by your header, footer or results pages should be referenced as /i/<installation id>/<file name>. For example if your installation id is 1234 and you have uploaded a graphic called "logo.gif" then your image tag should look like:

<img src="/i/1234/logo.gif">

Named Files used by WorldPay

If any of these files is missing then WorldPay defaults are used. The only exception is for resultY/C.html, where there is the alternative of using the result returned from the call back to the merchant site. This choice is determined by the settings on your installation (set via WAS). All these files are subject to parameter substitution as described below.

header.html - used for start of body of payment forms. Default is plain body open tag.
footer.html - used for end of body of payment forms. Default is plain body close tag.
resultY.html - complete html page for returning to customer if payment succeeds
resultC.html - complete html page for returning to customer if payment is cancelled
email template names are not yet decided (do not include graphics in email templates)

WorldPay Tags used in File Substitution

All files that WorldPay uses in construction of pages or emails are subject to parameter and file substitution. Substitution is carried out using special WorldPay tags as described below. These tags can be placed anywhere, including within HTML tags.

Substituting the value of a parameter

<WPDISPLAY ITEM="abcd" DEFAULT="def" PRE="pre" POST="post">

This tag is substituted with the value of the parameter named by ITEM. The names of parameter values that are available for substitution are listed in the appendix. Substitution is done as follows:

if the parameter value is available then prints "pre<value>post"
if the parameter value is not available then prints "def" (or "#null#" if no default given)

Embedding the contents of a file

<WPDISPLAY FILE="inner.txt" DEFAULT="not found">

This tag is substituted with the contents of the named file, which should be in your upload area. The embedded file can contain any WorldPay tags except for another file embedding command.

Embedding WorldPay tags within other WorldPay tags

The strings given as the values of WPDISPLAY attributes can themselves contain WPDISPLAY tags (except for file embedding tags). For example, given a cartId of 123:

<WPDISPLAY FILE="blurb<WPDISPLAY ITEM=cartId>.txt">

expands to:

<WPDISPLAY FILE="blurb123.txt">

which then results in the embedding of the file "blurb123.txt".

NB: don't use the same type of quotes in the inner tag: either omit them altogether as in the example above (only viable for single words) or use the other kind (single versus double quote):

<WPDISPLAY FILE="blurb<WPDISPLAY ITEM='cartId'>.txt">

Repeated Items

[Note that this will only become relevant once we allow multi-item shopping baskets]

If you have a shopping basket consisting of a series of items then you will need to use the LOOP command to repeat the template lines.

<WPDISPLAY LOOP="variable">
... lines to repeat ...
</WPDISPLAY>

These tags introduce a block of lines to be repeated. The variable named by LOOP is set to 1, 2, 3 etc. as the lines are repeated. This variable can be substituted in the repeated lines to enable you to number the items displayed. All WPDISPLAY tags are substituted as normal.

In addition a new tag is used for the items that are to change with each repeat:

<WPDISPLAY LOOPITEM="looping-item">

The name given for LOOPITEM has 1, 2, 3 etc. appended to and the value of that named item is then substituted for the tag. For example if <looping item> is "prodId" then prodId1, prodId2, prodId3 etc will be substituted in turn. If more than one LOOPITEM is included, the loop will continue until they all run out (so, for example, blank cells in a table are possible).

Loops cannot be nested.

Example of Looping

<WPDISPLAY LOOP=PQR>
  This is printed the same each time: <WPDISPLAY ITEM="cartId">
  Item number <WPDISPLAY ITEM="PQR"> cost: <WPDISPLAY LOOPITEM="amountString">
    <WPDISPLAY FILE="descrip-<WPDISPLAY LOOPITEM=prodId>.txt">
</WPDISPLAY>

results in:

This is printed the same each time: 123
Item number 1 cost: £10.28
This is printed the same each time: 123
Item number 2 cost: £50.00
This is printed the same each time: 123
Item number 3 cost: £25.45
This is printed the same each time: 123
Item number 4 cost: £5.39

WorldPay Banner placement

WorldPay always puts a standard banner into the final payment response page containing certain information that must be conveyed to the customer. The rest of this page is under the control of the merchant, as described in the section Payment Response Page. This banner is inserted at the point of the following tag:

<WPDISPLAY ITEM="banner">

This inserts the value of the variable "banner", which is the text of the WorldPay banner. If the merchant forgets to include that tag, it defaults to immediately after the BODY tag. If there is no BODY tag, then the banner goes at the top of the output.
Back to contents page

$Revision: 1.11 $