Service Archirecture
Cardsmobile TOTP Service operation principles
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:
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) and is passed over to the parnter's development team. 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 Cardsmobile.
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).
Refer to Barcode Display on Koshelek App Screen.
Another option is to put the full barcode value (barcode parameter) or the pre-separated card number and TOTP code (cardNumber and passCode parameters).
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.
Last updated
