POS Validation API

Introduction

The POS API allows retailers to automatically redeem coupons through their POS.

General principles

Background

Through the POS integration, retailer can redeem coupon codes from Liquid Barcodes. The process is a two step process. Step 1 is Reserve, Step 2 is Validate or Cancel.

Nomenclature

In order to maintain consistency throughout the description the following terms have been used. To avoid ambiguity they are defined here:

Coupon elements

The coupon is built up from certain elements:

The main elements of a coupon are:

• Code, this is the actual code that carries the real value of the discount. There is no limitation on the length of the code, nor is the code limited to digits only. However in practical implementations this code is 8 digits. This parameter is also known as UniqueCode
• Barcode, this a representation of the code in a form that is easy to scan. In order for the POS to identify the barcode as originating with Liquid Barcodes the content of the Barcode normally takes a form of ‘Prefix + Code’. The prefix part of the configuration for each retailer. The barcode is constructed in one of three ways (of which the first is the predominant structure)
• Prefix + UniqueCode. In total 12 digits.
• Prefix + UniqueCode + Control digit. This is only used when the barcode has to be of type EAN-13, where the last digit is a control digit.
• Prefix + ’01’ + CampaignCode + ’21’ + UniqueCode.

Process for validating coupons

The basic concept is that when a coupon/code is scanned/entered manually the system returns the corresponding reservation with conditions. This reservation is unique and subsequent uses of the same code/coupon will result in a new reservation with conditions that may or may not be identical to the first. Once the sale is completed, the reservation is either validated (the conditions have been met) or the reservation is cancelled/freed (the reservation’s conditions have NOT been met).

We use the term coupon or code as the representation of the offer to the consumer, and reservation as the singular, unique offer that corresponds to a particular use of the coupon. A coupon/code may in other words trigger multiple reservations with separate conditions.

The process of validation is done in two stages. Once the coupon is scanned or the coupon code is manually entered at the POS, a reservation request is sent from the POS to LIQUID (RESERVE function). Upon receipt of the RESERVE message LIQUID will respond with an acknowledgement message and this message may be positive (the coupon exists and can be used) or negative (the coupon doesn’t exist, is not valid, or has already been used). If the RESERVE response is negative an appropriate message to the cashier/consumer should be displayed, according to the error types described in this document.

A positive RESERVE response, called a reservation, will also contain conditions that need to be fulfilled before the rebate can be given to the consumer. Typical conditions are what products need to be on the receipt, the size and type of the rebate, a minimum total sale etc. A successful reservation will mark the coupon as reserved in LIQUIDs system, and this particular use of the coupon is locked until the reservation is either cancelled or validated. If the coupon can be used more than once, each use requires a separate reservation request, as the conditions for the rebate may change for each use of the coupon (an example would be a coupon that gives 5 % rebate for the first use, 10 % for the second, 15 % for the third, etc…). Once the sum of unconfirmed reservations and previous validations of a coupon/code equals the maximum number of validations it will no longer be possible to reserve the same code, unless one or more of the reservations are cancelled.

When the sale has been concluded, the POS has to determine whether the conditions for the reservation has been met (i.e. the required products are present on the receipt). When receiving payment from the consumer the POS must send a final confirmation to LIQUID containing whether  the consumer received the rebate. This is done through the validation request (VALIDATE function), as a confirmation or a cancellation. LIQUID will respond by sending VALIDATE response to confirm that it has received the validation. If no VALIDATE response is received the POS should retry at least 3 times.

If the rebate/coupon is removed from the receipt or the conditions have not been met, the POS should send a VALIDATE message and indicate that this reservation was cancelled. This will free the code for later use.

Cancelling reservations and clean up

Since coupons can be multi-use and each reservation can have different conditions the sequence of which reservations takes precedence is important. For reservations that belongs to the same coupon/code the reservations should be cancelled in the order of the most recent reservation first. As an illustration, a coupon has been reserved three times that gives 5, 10, 15 % rebate respectively on product A and 3 product A is present on the receipt. There are now two situations that needs to be handled properly:

• The cashier removes one of the product As from the receipt (irrespective of which of the three A’s is cancelled). In this case the last reservation (15 % discount) no longer holds, but both 5 and 10 % discount is still valid
• The cashier removes one of the reservations themselves (if made possible by the POS implementation). Regardless of which reservation that is removed, the most recent reservation should be cancelled (15 % discount)

System clean-up and parking the receipt

As a fail-safe in case the POS is unable to validate a reservation (by validating or cancelling), to prevent reservations from lasting indefinitely and to prevent that consumer is unable to use the coupon at a later stage, all reservations are automatically cleaned up 15 minutes after the reservation is made. If this occurs it is no longer possible to complete the validation (by validating or cancelling).

In the case where the receipt is intentionally parked/paused one risks that the clean-up happens while it’s parked. There are multiple alternative ways to handle this. The preferred option is the first one, however, depending on POS architecture and other factors, this may not always be ideal and the alternative implementation may be a better solution.

1. Cancel all reservations when unparking the receipt and immediately reserve them again.
   If the coupon has been used on another order in the mean time the reservation will fail, if not the reservation will go through.
2. Trying to make it before time-out.
   When the receipt is unparked the reservations can be in the following states and the POS will have to consider what to do with them.
   • Before the reservations time-out. The rebate is given and the validations will still go through, however, the time before validations must happen is reduced by the time the receipt was parked.
   • After the reservations time-out. When finalizing the purchase the validations will fail, and this should be handled by either replaying reservations. Alternatively, allowing the user scan his/her coupons again before finalizing the sale.
3. Cancel all reservations when parking the receipt.
   The user must be notified that the coupons will have to be scanned again.

Additional receipts

This API allows for additional receipts being printed which contains additional coupons. Note that these additional coupons will be issued on the basis of the initial transaction, and can hence not be used in the original transaction. As such this is a mechanism to get people to revisit your stores. There are two ways to invoke additional receipts and only one should be used per transaction:

• LIQUID Barcodes will add additional receipts to the transaction as a field on the VALIDATE response.This implies that there has been at least one coupon present during the transaction (note that the coupon may not give a discount in itself, but represent a membership card). The rules for which offer(s) to trigger for the additional coupons are then set up in LIQUID Barcodes system entirely, and conditions can span several purchases.
• The POS will during the finishing phase of the transaction query LIQUID Barcodes with the complete receipt for the transaction and an additional receipt may be returned based on either the total value in the purchase or which individual products were present. Note that this may issue coupon to any customer that has not already used a LIQUID Barcodes coupon in the transaction. To activate this functionality the POS needs to call the Receipt function call that is detailed below. If the user has used some LIQUID Barcodes coupon on the transaction, this function should not be called.

It should be noted that based on the configuration of the campaigns, and what information is available for the individual consumer, a receipt coupon may be distributed to the consumer through a different distribution channel. E.g. If the mobile number of the consumer is known to LIQUID Barcodes the system will distribute the coupon on SMS directly to the consumer. If the mobile number is not known the same coupon would be returned as an extra receipt to be printed by the receipt printer. The configuration of distribution channels is a property of the LIQUID Barcodes system.

Receipt text format

The format is a minimalist XML format. There is no XML-header used in the format and there is no XSD available.
Receipt texts are only used in the context of the Validation API and as such the enclosing HTTP response headers define the character set for this content.

Supported tags

<RECEIPTS>

This is the container tag for all additional receipts. There will be only one of this tag.

<RECEIPT>

This is the container tag for one additional receipt.

Supported attributes (default values underlined):

• reservationid=” X “
  If this receipt was created from a validation, this value references the reservation ID for the reservation+validation that triggered it.
  Optional attribute.

<BARCODE>

A barcode to add to the receipt. The value of the barcode is given as content for the tag.

Supported attributes (default values underlined):

• type=” datamatrix | ean13 “
  Format of the barcode. Required attribute.

<IMAGE>

An image to add to the receipt. The binary data of the image is given as content for the tag. Any whitespace characters should be removed from the content before decoding, as the content may have been chunked.

• format=” image/png “
  The image format used in the enclosed binary data. Required attribute.
  Currently the only supported format is image/png.
• encoding=” base64 “
  The encoding used on the enclosed binary data. Required attribute.
  Currently the only supported encoding is base64.

<TEXT>

A text paragraph, optionally formatted (see level four tags), to add to the receipt. All text content should be trimmed for any leading/trailing whitespaces. Multiple consequtive whitespaces should be treated as one whitespace. Linebreaks should be treated as spaces, as linebreaks are explicitly defines by BR tags.

Supported attributes (default values underlined):

• align=” left | center | right “
  Text alignment. Optional attribute.
• color=” #rrggbb ”
  Text color in hexadecimal red (rr), green (gg) and blue (bb) components. Optional attribute.

<B> for bold

The content of this tag should be formatted as bold text.

<I> for italic

The content of this tag should be formatted as italic text.

<SMALLER>

The content of this tag should be formatted slightly smaller than other text.

<BIGGER>

The content of this tag should be formatted slightly bigger than other text.

<BR>

Line break. Whitespaces before and after the linebreak should be trimmed.

<COLOR>

Supported attributes (default values underlined):

• color=” #rrggbb ”
  Text color in hexadecimal red (rr), green (gg) and blue (bb) components. Required attribute.

PoS Bandwidth and Latency Requirements

The amount of data transmitted through the API is quite limited with a typical payload of less than 1 kB (but it can be larger). In theory it means that the data can be transmitted over very low bandwidth networks. However the limiting factor is typically not the bandwidth but the latency as the network latency can significantly increase the time the consumer has to wait by the PoS for the transaction to finish. Additionally, as this service requires the PoS to be online at all times, the stability of the open connection is very important for the consumer experience at the PoS. A model for the time constraints related to processing of a reserve can be expressed as:

T_Reserve = T_Scan + T_{NetworkLatency} + T_Transfer + T_{LiquidBarcodesProcessing} + T_{NetworkLatency} + T_Transfer + T_{PoSProcessing}

= T_Scan + 2 * T_{NetworkLatency} + 2 * T_Transfer + T_{LiquidBarcodesProcessing} + T_{PoSProcessing}

where

• T_Scan is the time taken from the coupon has been scanned to the request from the PoS to Liquid Barcodes is initiated
• T_{NetworkLatency} is the latency of the network in question. This may vary significantly depending on the network configuration, and also includes the routing through the internet to the Liquid Barcodes servers
• T_Transfer is the actual transfer speed of the data packet. Given the small size of the payload this component would be ~150 ms for a 1kB packet over a 64kbit/s ISDN
• T_{LiquidBarcodesProcessing} is the time it takes for Liquid Barcodes to process the incoming request and send the response. Typically this is processed in 100 to 300 ms
• T_{PoSProcessing} is the time the PoS requires to process the incoming conditions from LB and align with the current transaction at the PoS

Additionally there is a second Validate function call that happens when you close the bill on the PoS which has the following time constraints

T_Validate = T_ClosingBill + T_{NetworkLatency} + T_Transfer + T_{LiquidBarcodesProcessing} + T_{NetworkLatency} + T_Transfer + T_{PoSProcessing}

= T_ClosingBill + 2 * T_{NetworkLatency} + 2 * T_Transfer + T_{LiquidBarcodesProcessing} + T_{PoSProcessing}

where

• T_ClosingBill is the time taken from the cashier closes the sale until the request to Liquid Barcodes is initiated
• T_{NetworkLatency} is the latency of the network in question. This may vary significantly depending on the network configuration, and also includes the routing through the internet to the Liquid Barcodes servers
• T_Transfer is the actual transferspeed of the data packet. Given the small size of the payload this component would be ~150 ms for a 1kB packet over a 64kbit/s ISDN
• T_{LiquidBarcodesProcessing} is the time it takes for Liquid Barcodes to process the incoming request and send the response. Typically this is processed in 100 to 300 ms
• T_{PoSProcessing} is the time the PoS requires to process the incoming conditions from LB and align with the current transaction at the PoS. Given that there is very little to process at this stage, the PoSProcessing step should be fairly insignificant.

Our recommendation is to have sufficient available bandwidth in order to minimise the latency. In the end the service will work with high latency too, but the wait for the consumer will at some point be unacceptable. We do however recommend to have a 500 kbit/s line from PoS to the internet (provided that the line is shared with other services), but as a minimum our service can operate reasonably well on a dedicated symmetric 64kbits/s line (that is always connected)

General notes for using the services

The API is available through a secure web service exposed at https://validator.api.barcodes.no/v3 . The client can expect a signed, valid SSL certificate for this endpoint.

Some standard HTTP response statuses are used to indicate success or failure. See Responses section below.

Authentication, timestamp and signatures are required for all services and are submitted as headers. See Requests section below.

All dates and times must be formatted as a ISO-8601 timestamp, for example 2014-03-06T13:11:04+03:00.

The unique coupon codes should not be added to the printed receipts, as it would allow a third party that gets access to the receipt to use another person’s coupons.

REQUESTS

All services require:

• Authentication via the HTTP header Authorization. We use the BASIC authentication mechanism. Username and password are provided by LIQUID.
• A timestamp via the HTTP header X-Liquid-Timestamp. It should be set to the current time when the client sends a request and must be formatted as a ISO-8601 timestamp, for example 2014-03-06T13:11:04+03:00.
  The services will reject any request where the time deviates more than 10 minutes from our current time.
• A signature via the HTTP header X-Liquid-Signature. See the section below on Calculation of the signature. 
  The services will reject any request where the signature cannot be verified.

RESPONSES

The HTTP response code will identify the outcome of any request.

• 200 (success): The request was successfull.
• 400 (bad request): A value in the request was considered wrong and caused the processing to stop. One typical value is the signature.
• 401 (unauthorized): There was a authentication problem (username and password is provided by LIQUID, contact support).
• 500 (internal server error): There was an unexpected problem (contact support).

Note that these codes are response-level status codes (as in one response, as a whole). In other words a 200 / success response may well contain rejected reservations / validations / cancellations. These can be identified by inspecting the nested RejectCode and RejectMessage fields. Furthermore a non-200 / unsuccessfull response code means the whole request has been rejected, with the exception of 500-errors which means something unexpected has occurred and the state is uncertain.

Unless another format is specified in the Accept header of the request, the format of the response body is JSON. The format of the response body can always be found in the Content-Typeheader.

Signature

In addition to authentication the services use a signature to further validate the customer and the authenticity of the request.

The signature is calculated from the following parts concatenated to a string (without any separator between the parts):

• The exact value of the X-Liquid-Timestamp header
• The content of the request (which fields and their order is specified in each services specification below).
• The secret salt provided to you by LIQUID.

The correct signature is the hexadecimal upper-cased SHA1 hash value from this content.

Example

Given the following:

• The customer salt is 123SALT123.
• The username is demouser.
• The password is demopassword.
• We want to reserve the UniqueCode 78907890.

The following is an example of a valid Reserve request:

POST https://validator.api.barcodes.no/v3/reserve HTTP/1.1
Accept: application/json
X-Liquid-Timestamp: 2015-02-10T22:53:44Z
X-Liquid-Signature: 25EC3D52BE0E728D4BF50A452B98E3E393C610AD
Content-Type: application/json
Host: validator.api.barcodes.no:443
Authorization: Basic ZGVtb3VzZXI6ZGVtb3Bhc3N3b3Jk

{
  "RetryCounter":0,
  "StoreRef":"MYSTORE001",
  "PosRef":"MYPOS002",
  "OperatorRef":"MYOPER003",
  "TransRef":"MYTRANS004",
  "InternalPosRef":"MYINTPOS005",
  "UserRef":"MYUSER006",
  "Codes":[
    {
      "UniqueCode":"12341234",
      "CampaignCode":"9876543210123" 
    }
  ]
}

Notice:

• Authorization header for basic HTTP auth.
  BASE64(“demouser:demopassword”) =  ZGVtb3VzZXI6ZGVtb3Bhc3N3b3Jk
• X-Liquid-Timestamp header format in ISO-8601 format.
• X-Liquid-Signature see detailed calculation explained below.

Looking at the Service specification in the next chapter you can see that signature source for the Reserve service is made concatenating the following data:

• StoreRef + PosRef + OperatorRef + TransRef + InternalPosRef
• All Codes items concatenated (no separator). Each item consisting of the following values:
  • UniqueCode
  • CampaignCode
• UserRef + RetryCounter

Which yields the same signature you can see in the requests X-Liquid-Signature:

modelsource = "MYSTORE001" + "MYPOS002" + "MYOPER003" + "MYTRANS004" + "MYINTPOS005" + "12341234" + "9876543210123" + "MYUSER006" + "0"
// modelsource is "MYSTORE001MYPOS002MYOPER003MYTRANS004MYINTPOS005123412349876543210123MYUSER0060"
 
source = "2015-02-10T22:53:44Z" + modelsource + "123SALT123"
// source is "2015-02-10T22:53:44ZMYSTORE001MYPOS002MYOPER003MYTRANS004MYINTPOS005123412349876543210123MYUSER0060123SALT123"
 
signature = UPPERCASE(HEX(SHA1(UTF8(source)))) 
// signature is "767778229A2A91E63BADA993AB79BE90F69E7AA9"

Disclaimer

This document describes the process flow and protocol for validating coupons issued by LIQUID Barcodes on behalf of the stores. In order to utilize this interface there must be a commercial agreement with LIQUID Barcodes in place, and a technical verification that the implementation has been implemented correctly. In all circumstances the intellectual property rights (IPR) of the interface resides with LIQUID Barcodes. LIQUID Barcodes reserves the right to change this interface at any moment. Any implementation that utilizes this interface is the sole responsibility of the implementor, and under no circumstances should the issuing of this document be construed to signify that LIQUID Barcodes will participate with the implementation, testing, verification of the implementation, unless otherwise agreed.

Standard POS Integration

Introduction

Liquid Barcodes POS Integration ensures quick and efficient customer experience in store. The member discount calculation is performed by Liquid Barcodes. This simplifies the POS integration.

• Customer identifies once in store.
• When all products have been added to the transaction, POS sends customer identification and list of products to Liquid Barcodes. Liquid Barcodes applies personal discounts. POS receives list of products and updated prices.
• When customer has paid and transaction has been closed, POS sends validation request to Liquid Barcodes. If customer wants to add products or on unsuccessful payment, POS sends cancel request to Liquid Barcodes.

The Standard POS integration uses the Applicator services – Reserve and Validate.

Applicator service – Reserve

API to be completed 2019.

Applicator service – Validate

API to be completed 2019.

Alternative POS integration methods

Integration alternatives

Liquid Barcodes offers multiple alternative POS integration methods.

In store handling

• Handle one coupon at a time
• Multi-use
• Identify once per transaction

How to communciate the offer conditions to the POS

• Promotion ID
• Conditions

The options are summarized and described in this table:

Identify once

Customer only registers once per transaction.

The API allows for the usage of unique User IDs instead of scanning individual coupons. The typical use case is that the consumer is identified by his membership number or registered payment method (eg. credit card) and will receive all the offers he is entitled to without having to scan multiple coupons. Note that the process of identifying the user ID from credit cards and translating from the credit card details to the unique user reference is not handled by LIQUID.

Once the user is identified, the POS can send a RESERVE request to LIQUID with the unique User ID in place of a coupon code. A successful reservation will return the collected results of a reservation for all of the users available coupons. That is, it will return the first available reservation for each coupon that the user is eligible for. Once the conditions for a reservation is met (and the corresponding coupon can be used several times) the POS must automatically fetch the next reservation for that coupon (see multi-use above).

Once the sale is completed and the products are paid for, all the reservations can be validated/cancelled in a single VALIDATE request.

Multi-use

This is a hybrid between the “One coupon at a time” and “Identify once” POS integration methods.

When scanning multiuse coupons, such as loyalty cards, POS automatically makes a new reservation when the offer conditions matches the product(s) on the receipt.

One attribute of a coupon is that it may be used more than once, e.g. three times, 5 times or unlimited numbers of times. The conditions for the rebate may differ for each subsequent reservation. To prevent that the consumer has to scan the coupon multiple times to use it multiple times on the same receipt, the POS should automatically reserve the coupon/code given that certain conditions are met.

When the conditions for a reservation is met, the coupon has more remaining validations and the coupon can be used more than once per sale, the POS should automatically reserve the coupon again and receive a new set of conditions. An example would be a coupon that can be used 3 times, and give a rebate when buying a particular product (A), The rebate given is 5 % discount first usage, 10 % discount second usage, and 15 % discount on the third and final usage. A consumer then scans the coupon at the POS (this initiates the first reservation), and adds product B, C and D on the receipt (which will not meet the conditions for the reservation). The consumer then adds product A, and the conditions for the first reservation is met. As the coupon can be used multiple times on the same sale and have remaining uses, the POS automatically reserves the coupon a second time and receives the second set of conditions. The consumer adds another product A, and the conditions for the second use has also been met, which triggers the third reservation. When the consumer adds the third product A the conditions for the third reservation is met, but as there are no further uses left the POS doesn’t reserve a fourth time.

In the example above, if at any time one of the product A’s is removed from the receipt, the rebate associated with the most recent reservation must be undone (the 15 % discount)

To simplify the process, all outstanding reservations can be validated/cancelled in a single VALIDATE request.

One coupon at a time

Shopper must register each coupon she wants to use one time per usage. Say for example she has bought two loyalty card products. She must scan her loyalty card two times to get two stamps on the loyalty card.

On each scan, Liquid Barcodes makes a reservation on the coupon code and replies with correct rebate conditions.

When transaction is complete, POS must validate the reservations that have been used.

If shopper scans too many times, POS must automatically cancel unused reservations.

This is a basic POS integration. It is easier to implement in the POS than the other integrations. The disadvantage is that it takes more time in store.

Offers based on Promotion ID

On reservation, Liquid Barcodes replies with Promotion IDs for the shopper’s personal offers.

The Promotion IDs are discount triggers that have been created in the POS before campaign start.

POS only applies Promomtion ID from each reservation once. To obtain additional Promotion IDs, new reservation must be made.

The advantage of using Promotion IDs is that discounts can be determined using POS existing rebate engine. The disadvantage is that the marketeer must maintain two systems – the coupon campaigns and the Promotion IDs.

The Promomtion IDs will be sent to POS using the ExternalParamater field in the Reservation response.

Offers based on Conditions

On reservation, Liquid Barcodes replies with rebate conditions for the shopper’s personal offers.

The rebate conditions define in detail the requirements for this particular rebate to apply and the value of the rebate.

POS only applies Conditions from each reservation once. To obtain additional Conditions, new reservation must be made.

The advantage of using Conditions is that the marketeer only needs to maintain one system. The disadvantage is that discounts must be calculated using a custom rebate engine in the POS.

The Conditions will be sent to POS using the Conditions field in the Reservation response.

Reserve

POST  https://validator.api.barcodes.no/v3/reserve

REQUEST

Signature

The signature source consists of the common header/salt data (see Calculation of the signature) and the following concatenated fields from this service:

• StoreRef + PosRef + OperatorRef + TransRef + LegalEntity + InternalPosRef
• All Codes items concatenated (no separator). Each item consisting of the following values:
  • UniqueCode
  • CampaignCode
• UserRef + RetryCounter

RESPONSE

Validate

This is the second part of the validation process. This is call is initiated in the following circumstances:

• The conditions for the reservation has been met and the customer is about to be given his rebate. This call is initiated after the customer has paid, but before the transaction has been completed.
• The conditions for the reservation have not been met so the reservation must be released.
• The transaction was aborted by cashier or customer so the reservation must be released.

POST https://validator.api.barcodes.no/v3/validate

REQUEST

Signature

The signature source consists of the common header/salt data (see Calculation of the signature) and the following concatenated fields from this service:

• RetryCount
  
• All Validations items concatenated (no separator). Each item consisting of the following values:
  
  • ReservationId + RebateValue + TenderValue
• All Cancellations items concatenated (no separator). Each item consisting of the following values:
  • ReservationId
• TotalValue
• Format
  
• Receipt
• All OptParams items concatenated (no separator between key/value, no separator between items).

RESPONSE