Skip to main content

Handover

There are many ways to handover a digital receipt to shoppers using the warrify API. Some of them require additional identification at the point of sale, such as a digital wallet pass or temporary ID. Others function completely seamlessly, matching sales to shoppers behind the scenes. This can happen, among other things, via payment information or customer ids.

info

To enable flexible ways to deliver receipts to shoppers it is required that ALL sales are sent to the warrify API (Not only those with a customerId or a com.warrify.warrify-card extension).

Below are some of the ways to deliver digital receipts to shoppers.

Loyalty App​

Using the checkout API one can offer a purchase history for registered shoppers. When a shopper presents their loyalty card at checkout send the customer id in the $.customer.customerId attribute. The purchases of a given customer can then be retrieved via a call to listSales by specifying a filter such as filter[query]=customer.customerId==056343.

Printed QR-Code​

One of the simplest ways is to add a scannable QR code to the printed receipt that will take shoppers to the digital receipt. When printing such a QR code make sure to use the URL in the $.data.links.permalink field of the createSale response.

Using a customer facing display (Dynamic QR-Code)​

When a customer facing display or sign-pad is present a unique QR Code that takes a customer straight to their digital receipt can be shown after checkout.

  • Gather line item information just as you would do normally.

  • Then process the payment as usual. This can be anything from cash, credit card to coupons.

  • After the payment send the line item, payment and general information in the specified format to the /sales/ endpoint.

  • In case of any error you SHOULD fallback to the physical printer to fullfil any legal obligations.

  • If everything worked out (HTTP Status Code 201 returned) the response contains the created sale. You SHOULD NOT issue a separate GET request to fetch the sale you just created. All data needed is in the response of the POST request. Inside the /data/links/ field you will find 3 links copy, original and permalink. Depending on whether a receipt was also printed you MUST use the original or copy link respectively to make it accessible to the customer. When a QR-Code is also printed on the receipt you MUST use the permalink link in the printed QR-Code.

    Some options include:

    • Display a QR-Code that contains the link on a second screen for the customer to scan.

    • Load the Link into a NFC tag for the user to scan.

    • Print the Link onto the print out of the receipt.

    • If you have an existing loyalty program which includes a mobile App, you MAY send the link (together with the customer id) to your backend which in turn sends the customer a push notification containing the link which the customer then can view in their browser or a webview inside your loyalty App. Though remember that in this case you are responsible for delivering the notification (possibly in a timely manner) to the customer.

Without a customer facing display (Temporary Warrify Card)​

If such a display is not available you can choose the second option and scan a code that is shown to you by the customer, similar to a loyalty card.

  • Gather line item information just as you would do normally.

  • During the checkout scan the code presented to you by the customer from their smartphone.

  • Then process the payment as usual. This can be anything from cash, credit card to coupons.

  • After the payment send the data inside the /data/extensions field as an extension of type com.warrify.warrify-card alongside the line item, payment and general information in the specified format to the /sales/ endpoint.

  • In case of any error you SHOULD fallback to the physical printer to fullfil any legal obligations.

  • If everything worked out (HTTP Status Code 201 returned) the response contains the created receipt. No further steps are required HOWEVER one can include a link to the receipt on the printout of the receipt. For this you MUST use the permalink link inside the /data/links field.

Supported Codes​

As of today we support the following types of codes:

QR​

The content of the QR code will be one of:

URL Encoded String​

An URL encoded string (e.g. p=wrfy&a=foo&b=Hello%20World&a=bar). This string will ALWAYS start with p=wrfy to uniquely identify a warrify QR code. Other parameters in the string will be arbitrary key-value pairs. You MUST NOT make any assumptions on the included data. The string will NOT include a protocol or hostname but simply uses the URL encoding for query parameters as a compact and safe transport encoding.

The contents of this URL encoded string MAY be decoded into a JSON object, where multiple occurrences of the same key MUST result in an array. The prefix p=wrfy SHOULD be omitted.

For example p=wrfy&a=foo&b=Hello%20World&a=bar results in

{
  "a": ["foo", "bar"],
  "b": "Hello World"
}

The contents of the encoded string MUST be sent in the attributes/content field of the com.warrify.warrify-card extension.

Reserved words​

The following parameters have a specific meaning.

key (case insensitive)typedescriptiondefault
prtenum: 0, 1Whether to print the receipt or not. If 0 DO NOT print.1 (meaning print by default)
URI​

An URI with the scheme wrfy (e.g. wrfy:?a=foo&b=Hello%20World&a=bar). Since this string will ALWAYS start with wrfy: it uniquely identifies a warrify QR code. Other parameters in the string will be arbitrary key-value pairs in the query section of the URI. You MUST NOT make any assumptions on the included data.

The contents of this URI query MAY be decoded into a JSON object, where multiple occurrences of the same key MUST result in an array.

For example wrfy:?a=foo&b=Hello%20World&a=bar results in

{
  "a": ["foo", "bar"],
  "b": "Hello World"
}

The contents of the encoded string MUST be sent in the attributes/content field of the com.warrify.warrify-card extension.

GS1-128 (formerly UCC/EAN128)​

As an alternative to the 2 dimensional QR code, which might not be supported by all barcode readers we allow the generation of GS1-128 codes. The GS1-128 uses Code128 as the representation. It works by using Application Identifiers to identify the intend of the data. The list of Application Identifiers in Section 3 of the GS1 General Specification lists codes 91 to 99 for internal use.

This means that an application identifier specific for each retailer needs to be designated for the warrify digital receipt. This should ideally be done as a configuration parameter, so that each retailer can configure it to avoid collisions. The warrify GS1-128 will have the following format, where [FNC1] denotes the "Function Code 1" of the GS1 standard and [AI] the selected Application Identifier. The data following the Application Identifier consists of an alphanumeric string ´[0–9, A–Z, a–z]´. Depending on the configuration this can be restricted to the character sets supported by the different Code 128 Subtypes.

[FNC1] [AI] 12345678901234567890

The data of the code (the part after the application identifier [AI]) has to be transmitted in the attributes/content field of the com.warrify.warrify-card extension.