Service Architecture
Warning
This service is deprecated. Use the Koshelek TOTP module instead.
TOTP Service operation principles
Authentication Mechanism
For authentication of a loyalty card in the issuer’s system, the Time-Based One Time Password (TOTP) mechanism is used: when the card is presented on the device screen, the Koshelek app forms a temporary password based on the card number. The temporary password is output on the Koshelek app screen together with the card number as a barcode, which the cash desk software scans and checks at the partner’s IT infrastructure.
Passcode Verification Library
Onetime password formed by the Koshelek app for presenting a loyalty card is checked by a special component Passcode Verify. The component is designed as a dynamic library (AAR, JAR, SO, and DLL formats are available for corresponding platforms). The library can be embedded into cash desk software as well as into the back-end (server) side of the partner’s software.
The Passcode Verify library checks the input password value and returns the result of the password verification. The partner’s software processes the presented loyalty card according to the verification result and implemented business rules (for example, it write-offs the loyalty bonuses if the card is verified, or does not use the card and bonuses, otherwise).
Library Call
To verify a TOTP password, call the Passcode Verify library and put values of the following input parameters: barcode, key, prefix, interval, passLength. All the parameters are mandatory. Any changes to constant values should be pre-agreed with Koshelek.
Barcode value scanned by a cash desk from the Koshelek app screen (or entered by a cashier manually) when the loyalty card is presented. The full value consists of a static part (prefix and card number) and a dynamic postfix (TOTP code).
Info
Another option is to put the full barcode value (barcode parameter) or the pre-separated card number and TOTP code (cardNumber and passCode parameters).
Example A (barcode):
CM2775599991258853
Example B (separated cardNumber, passCode):
2775599991258, 853
Private key of a partner (HEX string, 16 bytes, constant). The key value should be transferred to Koshelek in any secured way in advance.
Example:
70ac89d41ee665408409ffdb1b6596e0
Prefix value of a barcode (constant) which specifies that the card is presented from the Koshelek app. We recommend using the short prefix “CM” (“Cardsmobile” shortened).
Example:
CM
Time-to-live period of a TOTP code in seconds. Constant; recommended value is 300.
Example:
300
Length of a TOTP code in characters (digits). Constant; recommended value is 3.
Example:
3
After the Passcode Verify library processes the data, it returns a defined result of the TOTP code verification (the Boolean value; where “true” means that the code is valid). The partner’s software must process the value according to implemented business rules.
Example of TOTP Usage
The figure below presents an example of using the TOTP authentication to apply bonuses for customer during the purchase payment.
