Vend::Payment::Worldpay 1.0.0 $(3) is the home page with the latest version.

This package is for the 'Worldpay' payment system.

Quick Start Summary

1 Place this module in <IC_root>/lib/Vend/Payment/

2 Call it in interchange.cfg with:
    Require module Vend::Payment::Worldpay.

3 Add a new route into catalog.cfg (options for the last entry in parentheses):
  Route worldpay host (Live Payment URL)
  Route worldpay testhost (Test payment URL)
  Route worldpay instid 12345 (Your Worldpay instID)
  Route worldpay currency GBP (defaults to GBP)
  Route worldpay testmode 100 (Set to 100 for test mode 0 for live - default live)
  Route worldpay callbackurl (The URL Worldpay will callback eg
  Route worldpay callpw (Callback password, set any password you like and set it the same in the WP Admin Panel)
  Route worldpay fixcontact 1 (If set to 1 customers cannot ammend address details when they get to worldpay, 0 to allow changes)
  Route worldpay desc 'Yourstore Order' (Text to send in the desc field eg 'Yourstore Order')
  Route worldpay reporttitle 1 (If set to 1 will modifty order report title to include transaction ID)
  Route worldpay update_status processing (Text to set order status on success eg processing, default pending)
  Route worldpay wpcounter (Defines the counter for temporary order number, defaults to etc/username)

4 Create a new locale setting for en_GB as noted in ``item currency'' below, and copy the public space interchange/en_US/ directory to a new interchange/en_GB/ one. Ensure that any other locales you might use have a correctly named directory as well. Ensure that this locale is found in your version of locale.txt (and set up GB as opposed to US language strings to taste).

5 Add a new order profile in etc/profiles.order

__NAME__ worldpay fname=required b_fname=required lname=required b_lname=required address1=required b_address1=required city=required b_city=required state=required b_state=required zip=required b_zip=required &fatal = yes email=required email=email &set=mv_payment worldpay &set=psp worldpay &set=mv_payment_route worldpay &set=mv_order_route worldpay &final = yes &setcheck = payment_method worldpay __END__

6 Add the following fields to the transactions table if they do not already exist (run from a mysql prompt)

ALTER TABLE `transactions` ADD `wp_transtime` VARCHAR( 64 ) CHARACTER SET utf8 COLLATE utf8_general_ci , ADD `wp_cardtype` VARCHAR( 64 ) CHARACTER SET utf8 COLLATE utf8_general_ci, ADD `wp_countrymatch` VARCHAR( 64 ) CHARACTER SET utf8 COLLATE utf8_general_ci, ADD `wp_avs` VARCHAR( 64 ) CHARACTER SET utf8 COLLATE utf8_general_ci, ADD `wp_risk` VARCHAR( 64 ) CHARACTER SET utf8 COLLATE utf8_general_ci, ADD `wp_authentication` VARCHAR( 64 ) CHARACTER SET utf8 COLLATE utf8_general_ci, ADD `wp_authamount` VARCHAR( 64 ) CHARACTER SET utf8 COLLATE utf8_general_ci, ADD `wp_order_number` VARCHAR( 64 ) CHARACTER SET utf8 COLLATE utf8_general_ci, ADD `lead_source` VARCHAR(255) CHARACTER SET utf8 COLLATE utf8_general_ci, ADD `referring_url` VARCHAR(255) CHARACTER SET utf8 COLLATE utf8_general_ci, ADD `txtype` VARCHAR(64) CHARACTER SET utf8 COLLATE utf8_general_ci, ADD `cart` BLOB;

And run these to allow for temporary order numbers of greater than the default 14 character field type ALTER TABLE `transactions` MODIFY `order_number` varchar(32); ALTER TABLE `orderline` MODIFY `order_number` varchar(32);

7. Add the following to etc/log_transaction just BEFORE [/import][/try]

lead_source: [data session source] referring_url: [data session referer] cart: [calc]uneval($Items)[/calc]

8. Still in etc/log_transaction, find the section that starts ``Set order number in values: '' and insert this just before it:

[if value mv_order_profile =~ /worldpay/] [value name=mv_order_number set=``[scratch purchaseID]'' scratch=1] [else] and a closing [/else][/if] at the end of that section, just before the ``Set order number in session:'' line. The order number is generated by the module and passed to Worldpay at an early stage, and then passed back to Interchange with a callback. This prevents Interchange generating another order number. The module will not currently work with IC versions lower than 5.2 that use a tid counter defined in catalog.cfg. The initial order number uses the username.counter number prefixed with 'WPtmp', and a normal order number is created and the initial order number replaced only when Worldpay callsback that the card has been charged. This is to avoid gaps in the order number sequence caused by customers abandoning the transaction.

9. In etc/log_transction, change the line:- [elsif variable MV_PAYMENT_MODE] to [elsif value mv_order_profile =~ /worldpay/] add an OR if required eg [elsif value mv_order_profile =~ /googlecheckout|worldpay/]

Then in the [calc] block immediately below insert this line:

        undef $Session->{payment_result}{MStatus};

Within the same section change the following two instances of [var MV_PAYMENT_MODE] to [value mv_payment_route]

10. Creat a callback page in /pages called wpcallback.html or any name you prefer, set this page in the Worldpay admin panel, the module also supports dynamic callback pages where different catalogs can have different callback pages, if using this the callpage URL must be set in the route in catalog.cfg as described above.

At the top of the callback page include the following line:- [charge route=``worldpay'' worldpayrequest=``callback'']

At the end of the charge process Worldpay do not allow redirection to a receipt page, if you do this they claim they will disable the callback feature or even suspend your account, how nice! You can however re-direct if the transaction is cancelled

Worldpay will suck the wpcallback page back to their server and display it for you, this can be used to display a receipt page. The page will interpolate before being sucked to Worldpay so most items such as fname lname adress fields etc are usuable on the page. To display banners and logos they need to be pre-loaded onto the Worldpay server

At the top of the callback page just below the [charge route=``worldpay'' worldpayrequest=``callback''] you can test for a sucessful transaction as follows:-

[if type=``cgi'' term=``transStatus'' op=``eq'' compare=``Y''] [and type=``cgi'' term=``callbackPW'' op=``eq'' compare=``yourcallbackpassword'']

Display a receipt page


Display a cancelled page or bounce the customer back to site etc

[/else] [/if]

11. Checkout button

On your checkout page include a button that sets the route and submits the checkout form eg

    text=``Place Order''
   mv_todo=submit [/button]


  LWP::UserAgent and Crypt::SSLeay
  wget - a recent version built with SSL and supporting the 'connect' timeout function.


The Vend::Payment::Worldpay module implements the Worldpay() routine for use with Interchange. It is _not_ compatible on a call level with the other Interchange payment modules.

To enable this module, place this directive in <interchange.cfg>:

    Require module Vend::Payment::Worldpay

This must be in interchange.cfg or a file included from it.

The module collects the data from a checkout form and formats it with a re-direct to the Worldpay payment server. The customers details and cart is logged in the database before going to Worldpay with a temporary order number of the form WPtmpUxxxx where Uxxxx is derived from the username counter

If the transaction is sucessful the module processes the callback response from Worlday, if sucessfull the temporary order number is converted to an Interchange order number and a final route is run to send out the report and customer emails. Cancelled transactions remain in the database with the temporary order numbers but are automatically archived.

The module will also optionally decrement the inventory on a sucessfull transaction, if used the inventory decrement in log transaction should be disabled by setting the appropriate variable

The active settings.

The module uses several of the standard settings from the Interchange payment routes. Any such setting, as a general rule, is obtained first from the tag/call options on a page, then from an Interchange order Route named for the mode in catalog.cfg, then a default global payment variable in products/variable.txt, and finally in some cases a default will be hard-coded into the module.
Your installation id supplied by Worldpay, the module cannot be used without an instid, set in catalog.cfg
Worldpay requires that a currency code be sent, using the 3 letter ISO currency code standard, eg, GBP, EUR, USD. The value is taken firstly from the route parameter in catalog.cfg and defaults to GBP
Sets whether the system runs test or live transactions, set to 0 (default) for live transactions, or 100 for test transactions.
If using dynamic callback pages with Worldpay, set you callback page without the http eg:-

Sets the password to compare with the callback, set this the same as the password in the Worldpay admin panel
Sets the text for the desc field sent to Worldpay and will appear on the transaction reciper, eg 'Yourstore Order'
Fixes the information send to Worldpay so it cannot be modified by the customer at Worldpay, set to 1 to fix or 0 to allow the customer to edit address at Worldpay.
Set to 1 to change the email report title to include the Worldpay transaction ID, set to zero for standard report email title
Allows the order status to be set to any desired value after a sucessfull transaction, eg set to processing and all successfull transactions will have status processing, defaults to pending
Set to 1 for module to decrement the inventory on a sucessfull transaction, if used disable decrement via log_transaction.


Set testmode 100 in catalog.cfg

Add some items to the cart and place the order, the module will re-direct you to Worldpay where you can select the card type to pay with. Enter some test card details and check the order is logged in the database ok and emails sent out.

Test card numbers

Mastercard 5100080000000000

Visa Delta - UK 4406080400000000

Visa Delta - Non UK 4462030000000000

Visa 4911830000000

Visa 4917610000000000

American Express 370000200000000

Diners 36700102000000

JCB 3528000700000000

Visa Electron (UK only) 4917300800000000

Solo 6334580500000000

Solo 633473060000000000

Discover Card 6011000400000000

Laser 630495060000000000

Maestro 6759649826438453

Visa Purchasing 4484070000000000


Andy Smith <[email protected]> with help from and based on code by Lyn St George <[email protected]>, which in turn was based on original code by Mike Heins <[email protected]> and others.