Usage

TOTP verification of a loyalty card upon purchase with Koshelek Pay

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:

Pre-conditions

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

1. There is a 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

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 value to extract expected parts: prefix, loyalty card number, card session ID (cardSession), 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 value.
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/task, POST /checkout, POST /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 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: POST /availability-info, POST /checkout, POST /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 main flow, as described below.

Main flow, Step 7: TOTP barcode lacks prefix part, or prefix differs from expected (indicates that the loyalty card source is not 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 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 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 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 customer that operations with presented card are not possible.

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

The flow is identical to 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 founds that token received in headers of POST /availability-info/task, POST /checkout, POST /refund is not valid.
2. Koshelek Pay API server returns error to cash desk software.
3. Cash desk software displays error in UI.
4. Checkout operator notifies customer that operations with presented card are not possible.

Passcode Verify library methods

init()

Initialize library.

Input parameters

Output parameters

None.

barcodeVerify()

Verify barcode value.

Input parameters

Output parameters

getToken()

Obtain a token.

Input parameters

Output parameters