Click here to search the entire website

Securing payments

How to use our digital signature.

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

  • 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, CANCELLED and REFUSED.

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

Note:  You can ignore the HMAC, or even have it switched off.

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.

https://www.mymerchant.com/Success.jsp?orderKey=MYADMINCODE^MYMERCHANT^T0211010&paymentStatus=AUTHORISED&paymentAmount=1400&paymentCurrency=GBP&mac2=fdbdbc16fbe8d8e56159fc332a5293e32b3d6aea61f10849da5c28819ff56711

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:

orderKey:paymentAmount:paymentCurrency:paymentStatus

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

After concatenation

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:

MYADMINCODE^MYMERCHANT^T0211010:1400:GBP:AUTHORISED

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

856ff737b2987f21513b91992818d983ce9fed97847b15756c56493a23090415

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.

Payment page integration