Loyalty Tokens

A Loyalty Token is, simply put, a Credit Reception not yet assigned to a specific Contact. The Contact needs to 'claim' the credits reserved by the Loyalty Token through a link. Until that time, no Credit Reception is created.

One can create these Loyalty Tokens without having to communicate with our API, through our Business Dashboard. It's also possible to use our Public API to create a Loyalty Token.

Creating a Loyalty Token

A Loyalty Token is simply a URL, generated using a set of rules. This URL can be created without any API calls, as the rules are predefined. When the URL is visited - i.e., when it is the token is claimed - the Piggy backend can decode the URL, validate the token and allocate the credits to the contact in question.

Step 1: Generating the initial parameter string

In order to create a Loyalty token, the following parameters are required:

• version A version number indicating which token version you are using. The current version is v3.
• shop_uuid The shop UUID of the shop that is providing the credits.
• unique_id A unique id generated by the device/client that is creating the token (e.g. the order ID).
• timestamp A unix timestamp (this indicates the creation date of the token).
• unit_name Name of the unit for the corresponding value. Default if unsure: purchase_amount
• unit_value The value for which points are to be issued (e.g. the order amount).
• secret The secret that can be found in the client’s Account (this can be found here).

Use the parameters above to construct the initial parameter string. To illustrate, we’ll be using the following dummy data:

• version: v3
• shop_uuid: abcde-1235-hijkl-1i2k3
• unique_id: my_unique_id
• timestamp: 1646314054
• unit_name: purchase_amount
• unit_value: 10
• secret: very_secret

This generates the following initial parameter string:

Step 2: Hash the parameter string

Using the SHA-1 hash function, we can then convert this to a hash:

Step 3: Rebuild the parameter string

We'll now rebuild the parameter string, much like the initial parameter string, with two important changes:

• We will remove the secret parameter from the string
• We will add the hash parameter at the end, using the hash created in step 2.

This results in the following string (please make sure that the order of the parameters is exactly the same as displayed above):

Step 4: Create the final Loyalty Token URL

The query string from step 3 can now be used to construct the final Loyalty Token URL. Each Client has their own URL to their Contacts Portal, which can be found here. This can either be their own custom domain, e.g. https://acme.com, or a URL provided by the system, e.g. https://acme.piggy.eu. This will serve as the first part of the URL, followed by /l?hash= and then finally the query string.

The final result will look something like: https://acme.com/l?version=v3&shop_uuid=abcde-1235-hijkl-1i2k3&unique_id=my_unique_id&timestamp=1646314054&unit_name=purchase_amount&unit_value=10&hash=60585d543ff8bbd07ad9798b44241981b4e2d423

The Loyalty Token is now ready to be sent! When a Contact visits the link they're able to claim the credits embedded in the Loyalty Token, though, of course, only once.