The following guide is for developers who want to create Business Generated Links. Learn how to generate encrypted links using the programming language of your choice. But, before you start developing your own program, note that Trustpilot has developed some resources that can help you get started.
Read more about both resources in the
Authenticated Encryption on GitHubsection at the end of this document.
General guide for all programming languages
Business Generated Links use Authenticated Encryption with Associated Data (AEAD) and an approach called
Encrypt then MAC (EtM). Trustpilot uses one key to encrypt the
payload (encryptkey) and another key for the
MAC part (authkey) to ensure data integrity. These two keys can be obtained from your Trustpilot Business portal under the 'Business Generated Links' tab. If you don't see the tab, it is because you have to upgrade your account.
Here’s a step-by-step guide on how to create Business Generated Links:
- The keys copied from the Trustpilot Business portal are displayed in a
base64-encodedformat, so the first thing your application needs to do is a
base64-decodeof the keys.
- Create the JSON formatted
payloadobject and insert customer information. Please note: the following fields are required: email, name, and ref (reference number). Example:
To receive multiple reviews from the same customer, make sure to include a reference number every time you send them a Business Generated Link.
- Ensure the
payloadcannot be read by third-party interests, by encrypting the
payload. Encrypt with
AES-CBCusing a key size of
256 bits, a block size of
128 bits, and
PKCS7 padding mode
- Generate an
Initialization Vector (IV)according to the block size (
- Encrypt the JSON with the
- Create a signature of the
- Generate an
For this, we use HMAC-SHA256 and the
authkey. Compute the HMAC by
hashing the IV followed by the
HMAC = HMAC-SHA256( IV + ciphertext )
base64-encodethe IV +
base64_payload = base64( IV + ciphertext + HMAC )
- Finally, because
base64includes the slash (/) and plus (+) characters, it is necessary to
payloadabove before adding it to the final link. The final link should look like this:
payload = urlencode( base64_payload )
<domain> with your domain name and
<payload> with the
payload you generated in step 5.
The following flowchart shows the necessary steps involved in correctly formatting, encrypting, and preparing the
payload data prior to distribution:
How to verify that a Business Generated Link works
There are two ways of verifying that a Business Generated Link has been created correctly:
1. Test your link in a browser
- Paste your link into a browser and navigate to www.trustpilot.com.
- Select a star rating, add a title, and a review text.
- Now you can verify that your link works. If the name of the reviewer is displayed on the page then your encryption process is correct. If you are asked to log in using Facebook, Google, or Email, then your encryption process is incorrect.
- Please don’t post your test review.
2. Test your link with our command line interface (CLI)
You can install our command line interface (CLI) on your development computer. If you can decrypt your payload with the CLI, then you have encrypted your payload correctly.
Collecting product reviews with Business Generated Links
Collecting product reviews with Business Generated Links is easy. First add the relevant product SKUs to the payload and then upload your product catalog to Trustpilot.
1. Add product SKUs to your payload
Below is an example of a payload that includes product SKUs. It’s a simple JSON array.
2. Upload your product catalog to Trustpilot
To upload your product catalog to Trustpilot, provide your Customer Success Manager with a tab-separated file of all product details. The file should include the following column names (all lowercase):
- sku (required)
You can learn more about the format of this file here.
Once your product catalog is uploaded, our system is able to match a given product SKU with relevant product details, such as the URL of the product page on your site, the URL of the product image on your site, as well as the name of the product. Product details are then used to optimize your customer’s user experience. For example, when your customer is presented with the form where they will write the review, the form will include the name and an image of the product. Trustpilot also feeds product reviews to Google where they are used, e.g. in product listing ads.
“Authenticated Encryption” on GitHub
Here are some resources to help you get started with Business Generated Links:
1. Open source library for .NET
If your development language of choice is C-Sharp .NET, then you are in luck. We have generated a programming library that combines the .NET built-in AES and HMAC algorithms to provide an easy-to-use interface for doing authenticated encryption. Our library is based on this Gist by James Tuley: https://gist.github.com/jbtule/4336842, but modified slightly to only support the key based versions. Also, it does not use the GCM version, so there are no external dependencies. Please visit our GitHub repository and download the library here: https://github.com/trustpilot/nuget-authenticated-encryption
2. Open source command line client for Windows, Linux & Mac (beta)
We have also developed a lightweight command line client (program) your company can use to encrypt the data
payload to be included in the link. This option was developed to accommodate companies with limited programming resources. You can learn more and download this client here: https://github.com/trustpilot/authenticated-encryption-cli
3. Open source sample for the Python programming language
If your development language is Python, then simply download our Python implementation here: https://github.com/trustpilot/python-authenticated-encryption
4. Open source example for PHP
If your development language is PHP, then download our PHP implementation here: https://github.com/trustpilot/php-authenticated-encryption
5. Open source example for Java
If your development language is Java, then download our Java implementation here: https://github.com/NordeaOSS/authenticated-encryption