17.21. WorldPay
The WorldPlay plugin was updated in Nov 2023 to add the MD5 hashed signature field. If you are activating or updating WorldPay, please ensure you get the plugin DLL from the latest Kartris release. You will also have to add the new MD5Secret section from the .config file to your existing WorldPay.dll.config file.
17.21.1. Setup within Kartris
- Go to Configuration > Payment and Shipping Gateways and click to edit WorldPay.
- For the 'friendly name', enter the name you want this payment system to be referred to on the front of your site where customers select it, for example 'Pay by credit card with WorldPay'.
- Change the status from 'OFF' to 'ON' (for live orders) or 'TEST' or 'FAKE' for testing. 'TEST' means that a test order will be passed, allowing you to test the full integration and pass multiple orders and no cost without needed to do refunds. 'FAKE' means that Kartris will skip the WorldPay payment process and instead format a post back itself to the callback page of Kartris. This is useful for testing that the callback process works, triggers the appropriate emails and so on without keep having to keep going through the WorldPay test payment process.
- ProcessCurrency - If your WorldPay account can process orders in all the currencies you have available for customers to use on the site, then you can leave this blank to process the order in whatever currency the customer is using. If you cannot process all the currencies available, you can convert all orders to a specified currency at checkout. The total will be shown to the user in both currencies, with an explanation. For example, setting this to 'GBP' will convert all orders to British Pounds at checkout.
- Test URL - (for test orders) should be:
https://secure-test.worldpay.com/wcc/purchase - Post URL - (for live orders) should be:
https://secure.worldpay.com/wcc/purchase - AuthMode - This should be set to 'A' to authorize and bill transactions or 'E' to just authorize and hold funds (useful if you wish to do further fraud screening before accepting the payment). You will need to contact your WorldPay representative to set this facility up. Transactions can only be held unbilled for a few days before they lapse - see WorldPay’s documentation for further information. If you just hold transactions, you must login to your WorldPay admin area and manually choose to bill a transaction.
- InstallID - WorldPay will give you a unique number for your installation, which needs to go here.
- CallbackPassword - This value should match the password you set within your WorldPay account (see below)
- MD5Secret - text between 20 and 30 chars, including at least one upper case letter, one lower case letter, a number and a special character, but no spaces (despite what the WP documentation says!). This needs to match the same specified in your WorldPay account.
17.21.2. Setup within WorldPay
- Check the 'Payment Response Enabled' box.
- Enter the 'Payment Response URL' as http://www.yoursite.xyz/callback-worldpay.aspx
- Check the 'Enable Shopper Response' box. This will show a text version of the order on WP.
- Enter a callback password. This should match the one you specify in your Kartris back end.
- MD5 secret - this should match the value entered in your WorldPay account.
- Signature fields - enter instId:amount:currency:cartId
- If you want to have a standard looking WorldPay confirmation page, uncheck the 'Enable Shopper Response' box. You can then customize the page returned using resultY.html and resultC.htm pages.
http://www.worldpay.com/support/kb/bg/customisingadvanced/custa7105.html
17.21.3. Templating the WorldPay response
For security reasons, WorldPay restricts the HTML tags that can be used in the template. Javascript and embedded objects are banned. You should refer to WorldPay documentation for more details.
The response to WorldPay from Kartris is formatted using a file which should be placed here on your site:
/Skins/[your skin]/templates/Callback_RBSWorldPay.html
17.21.4. Adding the new MD5 support
If you are updating an existing Worldpay installation, you will need to do the following.
17.21.4.1. Add the new Worldpay payment DLL
You may need to stop the web site in IIS first to unlock the existing DLL. Then copy the new Worldpay.dll file from the latest Kartris zip (/Kartris/Plugins/Worldpay folder) into your web, overwriting the existing file. Then you can restart the web site in IIS.
17.21.4.2. Add the new setting to your Kartris site
Find the Worldpay.dll.config file in the same folder as the Worldpay.dll you just changed. Open this in notepad for editing and add this new section into the settings, ideally between the CallbackPassword and InstallID ones. The new section looks like this:
<setting name="MD5Secret" serializeAs="String">
<value />
</setting>Now, we need to add a value to this setting. Go to your Kartris back end, Configuration > Payment and Shipping Gateways and you should see Worldpay near bottom. The verson should show as 2.1.0.1 (or above). Click to edit Worldpay.
You should see the new MD5Secret field. Add a value - this should be text, between 20 and 30 characters, no spaces. It must contain at least one number, one lowercase letter, one uppercase letter and one special character. Copy this value as you'll need it in the next step.
17.21.4.3. Add the setting into the Worldpay admin panel
You need to login to Worldpay, find the live account settings for the correct install ID and update a couple of fields.
First, the MD5 Secret. You should copy exactly the same value into the new MD5Secret field you just added into your Kartris back end.
You will also need to add the following to the Signature fields: instId:amount:currency:cartId
Save the settings. If there are errors reported with your MD5 Secret value, fix them, but ensure that you copy any changes back into Kartris, so your MD5 secrets in both places match.