Nibble Payload
The Nibble Payload is a cryptographically signed, url-safe string that can be used to verify the details of a successful Nibble. It can be freely used in non-tamper-proof environments (e.g. in browser). However, you must only verify the payload in a secure environment, because doing so requires knowledge of your Nibble API Secret.
The payload can be useful in scenarios where data relating to Nibble discounts are stored in insecure locations. For example, if customer carts are stored in cookies rather than in a server-side database, the payload can be attached to items via cookies and then verified server-side at checkout to confirm that the Nibble data has not been tampered with.
Format
The Nibble payload is a string containing two parts, the content and the digest, separated by a period . Both
parts are encoded using URL-Safe Base64 encoding, so that the entire string is URL-safe.
Content
The content half of the payload is a JSON object containing all the relevant Nibble details, seralized to a string and encoded using URL-Safe Base64. The JSON object contains the following items:
| Field | Type | Description |
|---|---|---|
nibble_id | string | Unique ID of the Nibble. |
session_token | string | The session token passed to the Create Nibble endpoint when the Nibble was created. You should check that this session token matches the previous known value to ensure that this Nibble payload has not been passed to another user, session or cart. |
currency | string | ISO 4217 alphabetic code of the currency used for this Nibble. |
issued_at | string | ISO 8601 DateTime indicating when the payload was generated, in UTC. You can use this to determine the age of the payload. We recommend expiring Nibble discounts after 24 hours. |
product_discount | object | If the negotiation type was set to product when the Nibble was created, details of the product discount will be present in the product_discount object. |
product_discount.product_id | string | The same product ID passed to Create Nibble. Use this to verify that this payload is valid for the item in cart - if the product ID does not match, the user may have attempted to apply this payload to a different product. |
product_discount.variant_id | string | The same variant ID passed to Create Nibble. |
product_discount.quantity | integer | The quantity of the selected product that was agreed on during negotiation. You should take care to ensure that this is the quantity that is added to cart. We recommend invalidating the discount if the user changes a quantity after negotiation. |
product_discount.original_total_price | decimal as string | The normal retail price of the specified quantity of this product. Should match the price provided to Create Nibble, except where quantity has changed (this value can be viewed as the unit price multiplied by quantity). You should verify that the original total price is as expected for the product, otherwise the user may have attempted to tamper with prices. |
product_discount.discounted_total_price | decimal as string | The price agreed to during the negotiation. This prices is guaranteed by Nibble to be between your original total price and the discount threshold defined in your rules. Assuming all other data in the payload is correct, and the payload has been validated correctly, you are safe to apply this price to the line item. Note: this price is the total price depending on quantity, i.e. discounted unit price multiplied by quantity. |
cart_discount | object | If the negotiation type was set to cart when the Nibble was created, details of the cart discount will be present in the cart_discount object. |
cart_discount.original_total_price | decimal as string | The normal price of all items in the cart, before Nibble discounts, shipping and taxes. This should match the amount passed to Create Nibble. If the user’s cart has changed after the Nibble negotiation, you should ensure that the discount no longer applies. |
cart_discount.discounted_total_price | decimal as string | The price agreed to during the cart negotiation. This prices is guaranteed by Nibble to be between your original total price and the discount threshold defined in your rules. Assuming all other data in the payload is correct, and the payload has been validated correctly, you are safe to apply this price to the cart total. Note: this price is the total price of all items before shipping and taxes. |
addon_items | array of objects | If a free gift was offered and agreed to during the negotiation, or other free items were added, they will appear in this array. Free gift/addon items should only be added to the cart alongside the original product (or alongside all items in a cart negotiation). If the original product (in a product negotiation) is removed from the cart, or if the cart changes (in a cart negotiation), you should take care to also remove any free gifts. |
addon_items[].product_id | string | The addon_items field is an array of objects, each with a product_id. This product ID is the ID of the product that Nibble has agreed to provide as a free gift. It should be added to the cart after a successful negotiation. |
requested_action | string | Either add_to_basket or checkout, depending on the user’s selection. If set to checkout, you should add the item(s)/discount(s) to cart and take the user to checkout immediately. |
Digest Validation
The digest part of the payload is a cryptographically signed digest of the content part, using the HMAC SHA256 authentication standard with the Nibble API Secret as the shared secret. To verify a payload, the steps are as follows:
- Split the
payloadintocontentanddigestusing"."as the separator. Discard the"." - Using Url-Safe Base64, decode the
contentinto a UTF-8 string - Using Url-Safe Base64, decode the
digestinto a UTF-8 string - Using your Nibble API Secret as the HMAC key, generate the HMAC-SHA256 digest of the
contentstring - Verify that the digest you have generated matches exactly the
digestprovided.
If and only if the digest provided matches the digest you create using your Nibble API Secret and the content, you can
be assured that the content has not been tampered with and was generated by Nibble without interference. You can
therefore be confident that the discounted price is valid.
Once you have validated the payload, you can parse the content string into a JSON object and use the data provided
(as listed above) to apply the discount.
Sample Code
The Nibble team is working on providing sample code for payload verification in a range of programming languages; if you require assistance or guidance please contact your account representative and Nibble will attempt to assist you.