Koshelek TOTP Module
Documentation has moved
The information on this page is no longer updated and may be obsolete. The most current Koshelek documentation is now available at the new address:
General information
Koshelek TOTP is a software module that implements authentication (authenticity check) of mobile loyalty cards issued in the Koshelek app and presented on the application screen at the checkout in a retail store during payment with Koshelek Pay.
Module purpose and authentication mechanism
Koshelek Pay uses Time-Based One Time Password (TOTP) mechanism to authenticate loyalty cards in merchant's system and to identify whether the presented card supports payments with Koshelek Pay.
When a customer selects a card, the Koshelek app builds up a short-living one-time password based on card prefix and card number.
This temporary password is combined with the card number, and then it is shown on the card presentation screen as a barcode.
Merchant's cash desk system scans it and verifies in merchant's infrastructure.
Koshelek TOTP module provides backward compatibility for cards uncapable of Koshelek Pay (for example, if merchant's card is shown on older version of the Koshelek app). For such cards, only card authenticity is verified.
If payment with Koshelek Pay is available for the card, Koshelek TOTP module creates a secret token, which the merchant integrates in a Koshelek Pay checkout request. The checkout is possible only if a valid token is presented.
That is, Koshelek TOTP module provides the following features:
Barcode parsing for merchant's loyalty cards presented from the Koshelek app.
Customer authentication in merchant domain.
Extraction of loyalty ID.
Extraction of payment session ID.
Integrity and authenticity control of payment requests.
Example of TOTP barcode built with the Koshelek App:
If your loyalty program relies on one-dimensional barcodes (for example, code128), then the maximum value for your barcode will be built up from the following data:
prefix— max 2 symbols (Latin characters and / or digits);cardNumber— max 13 digits with the prefix / max 16 digits without the prefix;cardSession— server generated card presentation session code, 6 characters by default;delimeter— a separator before the TOTP password value;TOTP password— 3 digits depending on your TOTP profile configuration.
If your fullBarcode value tends to exceed above length limits, then you have to go with two-dimensional barcodes as too-lengthy one-dimensional barcode may not fit on the screen for normal barcode scanner to read.
Last updated
