Usage

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:

https://developers.koshelek.app/en/

Processing loyalty cards with Koshelek TOTP Module

The diagram below describes data flow when a customer presents loyalty card with TOTP-enabled barcode at the checkout:

(for full resolution, open image in new tab)

Pre-conditions

The scenario will properly execute when the following pre-conditions are met:

1. There is Koshelek TOTP Module deployed on your cash desk server.

2. The Koshelek TOTP Module is configured (refer to Setup and Configuration).

3. The Passcode Verify library is initialized on your cash desk server (refer to Setup and Configuration).

4. Your cash desk software is updated to process Koshelek TOTP Module responses returned on the barcodeVerify() calls.

5. The Koshelek Pay server has all services configured to communicate with your environment.

Main flow

For library methods mentioned in subsequent flow, please refer to "Passcode Verify library methods" below in this document.

1. Customer selects your loyalty card in the Koshelek app.

2. The Koshelek app requests data required for TOTP barcode generation.

3. The Koshelek app renders the TOTP barcode on the screen.

4. Checkout operator scans the TOTP barcode value.

5. Cash desk software processes the TOTP barcode value.

6. Cash desk software communicates the fullBarcode value to cash desk server, which uses it as an input parameter for making a barcodeVerify() call to Koshelek TOTP Module deployed on the server.

7. Koshelek TOTP Module parses fullBarcode to extract expected parts: prefix, loyalty card number, card session ID, and TOTP password.

8. Koshelek TOTP Module takes the extracted parameters and validates:

   • If TOTP password is valid.

   • If bonus points operations are available for loyalty card.

   • If Koshelek Pay is available for loyalty card.

9. Koshelek TOTP Module responds to cash desk software. The response contains:

   • Response code: resultCode = CARDSESSION_AVAILABLE

   • TOTP password validation result: totpCodeValid = true

   • Loyalty card number: cardNumber

   • Koshelek Pay payment session ID: cardSession

   • Full barcode value: fullBarcode

10. Cash desk software processes successful result and caches cardSession.

11. Checkout operator suggests payment with Koshelek Pay.

12. Customer confirms payment with Koshelek Pay.

13. Cash desk software builds a payment initialization request for methods POST /availability-info, /checkout, /refund and puts the request in temporary storage.

14. Cash desk software communicates the saved request body in JSON to cash desk server, which uses it as a requestData input parameter in the getToken() call to Koshelek TOTP Module deployed on the server.

15. Koshelek TOTP Module receives the getToken() request with the requestData as an input parameter.

16. Koshelek TOTP Module generates a token.

17. Koshelek TOTP Module returns the token value as output parameter to cash desk server.

18. Cash desk software puts token in header for all subsequent Koshelek Pay API requests: /availability-info, /checkout, /refund.

19. Koshelek Pay API server receives requests with the token in header.

20. Koshelek Pay API server validates token and processes requests as per current scenario.

21. Koshelek Pay API server returns a successful response to cash desk server and generates an invoice to display in the Koshelek app.

22. The further flow for cash desk goes according to the Koshelek Pay transaction processing flow (refer to Usage Scenarios).

Alternative flows

There are several branches that extend the main flow:

Main flow, Step 7: TOTP barcode lacks a prefix part, or the prefix differs from the expected one (indicates that the loyalty card source is not the Koshelek app)

1. Koshelek TOTP Module sends the following response to cash desk software:

   • Result code: resultCode = ANOTHER_INSTANCE

   • Unsuccessful validation result: totpCodeValid = false

   • Loyalty card number missing: cardNumber = null

   • Koshelek Pay session missing: cardSession = null

   • Full barcode value: fullBarcode

2. Cash desk software processes the response.

3. Further payment scenario is performed as if the card source is not the Koshelek app (without loyalty bonus operations and without Koshelek Pay as a payment option).

Main flow, Step 7: loyalty card is valid, but TOTP barcode lacks cardSession (indicates unavailability of Koshelek Pay payments for card)

1. Koshelek TOTP Module validates TOTP password. Result: password is valid.

2. Koshelek TOTP Module sends the following response to cash desk software:

   • Result code: resultCode = CARDSESSION_NOT_AVAILABLE

   • Successful validation result: totpCodeValid = true

   • Loyalty card number: cardNumber

   • Koshelek Pay session missing: cardSession = null

   • Full barcode value: fullBarcode

3. Cash desk software processes response.

4. Further payment scenario is performed with loyalty bonus operations but without Koshelek Pay as a payment option.

Main flow, Step 7: loyalty card is invalid (error with bonus operations, no further actions with card are possible)

1. Koshelek TOTP Module validates TOTP password. Result: password is invalid.

2. Koshelek TOTP Module sends the following response to cash desk software:

   • Result code: resultCode = VALIDATION_FAILED

   • Unsuccessful validation result: totpCodeValid = false

   • Loyalty card number: cardNumber

   • Koshelek Pay session missing: cardSession = null

   • Full barcode value: fullBarcode

3. Cash desk software processes response.

4. Cash desk software outputs error in UI.

5. Checkout operator notifies the customer that operations with the presented card are not available.

Main flow, Step 8: loyalty card is invalid (error with bonus operations, no further actions with card are possible)

The flow is identical to the previous one.

Main flow, Step 21: Koshelek Pay API server found token to be invalid (no further actions with card are possible)

1. Koshelek Pay API server finds that the token received in headers of POST /availability-info, /checkout, /refund is not valid.

2. Koshelek Pay API server returns an error to cash desk software.

3. Cash desk software displays the error in UI.

4. Checkout operator notifies the customer that operations with the presented card are not available.

Passcode Verify library methods

Method names may vary slightly, depending on particular library format being used.

Initialize (init)

Input parameters

Parameter	Type	Mandatory	Description
algorythm	String	Yes	Encryption algorythm being used: HMACSHA256 HMACSHA1
passLength	Int	Yes	One-time password length. Max. value = 10.
prefix	String	Yes	Barcode prefix. Default value = CM.
key	String	Yes	Partner's private key (HEX string) required to build a password.
interval	Int	Yes	Password validity interval (in seconds).
cardSessionLength	Int	Yes	cardSession parameter length.
delimeter	String	Yes	Delimiter for barcode parts.

Output parameters

None.

Verify barcode value (barcodeVerify)

Input parameters

Parameter	Type	Mandatory	Description
fullBarcode	String	Yes	Barcode value.

Output parameters

Parameter	Type	Mandatory	Description
resultCode	String	Yes	Depending on scenario, either of the following values may return: CARDSESSION_AVAILABLE ANOTHER_INSTANCE CARDSESSION_NOT_AVAILABLE VALIDATION_FAILED
totpCodeValid	Boolean	See Description ->	true If fullBarcode contains TOTP password and loyalty card is valid. false if fullBarcode contains TOTP password and loyalty card is invalid. false if fullBarcode does not contain TOTP password.
cardNumber	String	See Description ->	Always returned except for when prefix is not available or does not match the one specified in configuration (i.e. the barcode source is not Koshelek). Returns null if barcode source is not Koshelek.
cardSession	String	See Description ->	Returns cardSession obtained from fullBarcode. Returns null if fullBarcode does not contain cardSession.
fullBarcode	String	Yes	Barcode value obtained by library from cash desk barcode scanner.

Obtain a token (getToken)

Input parameters

Parameter	Type	Mandatory	Description
requestData	String	Yes	A string containing JSON response body for POST /checkout.

Output parameters

Parameter	Type	Mandatory	Description
token	String	Yes	A token to be used in request header in POST /checkout.