Securing payments

How to use our digital signature.

Worldpay's redirect message to the result URL contains a number of parameters that include:

  • orderKey, paymentAmount, paymentCurrency, paymentStatus
  • A digital signature, called the Message Authentication Code (MAC)

About the MAC

The MAC provides a digital signature that allows you to verify that the redirect message:

  • Originated from Worldpay
  • Has not been modified since Worldpay signed it

After successfully verifying the redirect message you can reliably use its information to update the order's payment status on your system. This method applies to the payment statuses AUTHORISED and REFUSED.

We recommend that you use other payment status reporting tools (such asorder notifications), to update the order's payment status on your system.

Note: You can ignore the HMAC, or even have it switched off. We don't recommend this if you don't useorder notifications.

Creating and adding the MAC

The MAC is created using a key-dependent one-way hash function (HMAC-SHA256). To secure the signature:

  1. A secret value (password), known only to you and Worldpay, is added to the redirect parameters before the hash value is calculated
  2. The hash value is then added to the redirect message when it is sent, but the secret value is not

In this example the signature (MAC) is added to the message as a hexadecimal representation of the hash value.


Calculating the hash value

When you receive the signed redirect message, you can calculate the hash value in exactly the same way, by:

  • Adding the secret value to the parameters of the message. All parameters must be separated by colons (:)
  • Applying a HMAC-SHA256 algorithm to the message

The calculated hash value should exactly match the hash value that Worldpay has added to the redirect message.

When Worldpay redirects the shopper from the payment pages to the result URLs, the definition of orderKey that is used (orderKey=ADMINCODE^MERCHANTCODE^orderCode) is different from that used for redirecting the shopper to the payment method selection pages (orderKey=MERCHANTCODE^orderCode).

Calculating the HMAC-SHA256

The HMAC-SHA256 is calculated over the sensitive data in the redirect message (not the entire redirect message). To calculate the HMAC-SHA256, the values of the following parameters, and in the following order, are concatenated, separated by colons:


Note: Other parameters
An actual redirect message can contain more variables than shown in the example, but the above variables are included in the calculation of the MAC. If the shopper clicks 'Cancel' on the payment page, this results in an order without paymentStatus. Instead the following string is combined with the MAC secret:

After concatenation

The message is fed into an HMAC-SHA256 hashing function (with the secret) - which returns a 256-bit value.

The hexadecimal representation of this value must be compared with the value of the MAC provided in the signed redirect message. Worldpay always uses lower-case hex characters.

To verify a redirect message, concatenate the variables as below. Where the MAC secret is @p-p1epie:


This is fed into the HMAC-SHA256 function in your programming language, with the secret. The hex representation of the resulting hash value is:


This calculated MAC equals the value provided in the signed redirect message. This guarantees that the message corresponds to order code T0211010 (above) with a successfully authorised payment for £14.00 (GBP)

Setting the MAC secret

The MAC secret (password) is set in the Merchant Interface > Profile page. The MAC secret must be a combination of English alphanumeric characters and symbols, between 20 and 30 characters long. It must have all of the following:

  • An upper case letter
  • A lower case letter
  • A number
  • A symbol which can be any of the following:
    {~, !, @, #, $, %, ^, &, *, (, ), _, +, -, =, `, \, ], [, \, ;, :, /, ., ,, |, }, {, ", ?, >, < }

The MAC feature is enabled with a system-generated password. You are only required to enter a new password and save the profile to be able to check the MAC in the redirect message. The redirection of the shopper to your result URL is not affected if the MAC feature is enabled without the MAC being checked.

You can also disable the MAC feature in the Merchant Interface. However, this will cause the previously set password to be lost.