POS (Point of Sale) & Cards quick steps

From Cyclos4 Wiki
Jump to: navigation, search


The POS module in Cyclos allows users identified with a "User identification method" to perform payments at a "POS" (Point of Sale). The typical user identification method is a "token". A token can be a card, like an NFC (RFID) card, a card with a QR or bar code, or magnetic (swipe) card, but it can be any sort of identifier (in the future we could add for example a "finger print" token type).

A user with a POS (Point Of Sale) can accept payments from users with a token/card. This can be done either at an existing POS device already present in the store, a mobile phone or tablet that has the Cyclos mobile app installed or through the normal web interface (Receive payment option).

Smartphone NFC POS

The Cyclos mobile app has a "normal mode" (for payments etc.) and a "POS mode". Usually the POS mode is only enabled for merchant groups. Currently this app supports receiving payments by NFC, barcodes/QR-codes and all simple (not secure) user identification methods (such as account number, email, login name, mobile phone, or a custom profile field). If you want a highly secure system we would recommend only allowing NFC payments, since here the 128bit AES encryption ensures a good authentication of the customer. The NFC POS is currently only available for Android. In the future NFC support for other devices might be added.

Guides overview:

  • If you have your own POS devices that you want to handle in Cyclos or if you have a complete POS system that can be connected to Cyclos, the Cyclos API should be used. Please check our latest documentation: http://www.cyclos.org/documentation
  • If you have problems configuring the POS or if you want a quick demo you can use our nfc POS demo cummunity: https://communities.cyclos.org/nfc


  • Please always hold the card away from the device at least 30 cm and only hold the card close to the device if the device asks for the card, to ensure an optimal initialization and contact with the card.
  • Sometimes the signal is to weak for some cheap nfc chips to let the card perform the heavy cryptographic calculations (needed to receive a payment), make always sure to hold the card as close to the phone as possible and try to find the best position to hold the card.
  • Sometimes when Android beam is activated it can give problems, we have had this feedback from a user with a "OnePlus One" phone, with the models we tested Android beam didn't give problems.

Smartphone NFC configuration guide

The steps below need to be done by an admin, preferably a network admin with full permissions over the network. Only when mentioned explicitly in a bullet, that specific action doesn't have to be executed by an admin.


  • Android smartphone with an NFC chip
    • The nfc chips of NXP work all without problems e.g. NXP PN547, NXP PN544.
    • There are not so many devices with a broadcom chip, but they can give problems (the BCM20793M works fine but BCM20794 can give problems).
    • Which chip is used in which device can be found here: https://en.wikipedia.org/wiki/List_of_NFC-enabled_mobile_devices
  • Cyclos mobile app installed (it can be downloaded here: https://play.google.com/store/apps/details?id=org.cyclos.mobile).
  • NFC card: MIFARE DESFire EV1 (all memory sizes are supported 2 KB, 4 KB and 8 KB). The DESFire Light is not supported!
  • We assume that the POS functionality is introduced in a system that already has some users. At least there should be an user that will receive the payments (a shop) and a user that will pay at the POS (a customer), they should both have their own product. If no users are present in your system please create them first. Some knowledge about Cyclos is required to install the POS. If you do not have this knowledge we would recommend to watch these videos first: http://www.cyclos.org/documentation/cyclos-4-pro-instruction-videos/

Step 1: Create a token type

A token represents an identifier of a user. This identifier is usually stored at a card, for example NFC, bar-code or magnetic (swipe) card. The card can be associated to a user so that the latter can perform actions at a POS (Point of Sale), which are typically merchants. Token types are the templates for tokens, much in the way that transaction types are the templates for transfers/payments. Token types can have various configuration options and status. All token type details and rules are described in the Access_-_Tokens. In this example we will create an NFC card to work with the mobile app.

  • Create a new token, go to: System > System configuration > User identification methods > New > Token.
    • The fields of the Token type are straight forward. If any doubts you can look at the Token specification.
    • For the mobile NFC smartphone POS make sure to select "NFC tag" (under type).
    • In this example we call the token NFC card and make sure to save the new user identification method.
  • Enable the token for the customer, go to: System > User configuration > Products (permissions) > [select the product the customer uses] > My tokens, make sure to enable the token NFC card and save the product. If you want to give the customer more permissions over his token the other options can be selected too. In this case the user (customer) can login in Cyclos and go to: Personal > Settings > [Name of the token].
  • Give an admin group the permissions to manage the tokens/cards, go to: System > User configuration > Groups > [select the group that should manage the token] > Permissions (tab) > User management > User tokens, for testing purposes it would be easiest to select all options (or at least View, Initialize and Personalize). Later these options can be given to different admins with different roles.

Step 2: Enable card (token)

In order for customers to pay at shops/commerces the following steps need to be done.

Card payment settings for customers (payers)

  • Firstly the 'Pay at POS' channel needs to be enabled for the users that will do the payments at the POS (the customer with the card). Go to the configuration of the customer: System > Configurations > select configuration form list > Tab Channels > Pay at POS. Make sure check the 'enable' option in the channel details, and set the confirmation password to "Enabled by default" (so the customers don't need to enable by themselves). You can use the 'login password' or 'PIN', or you can use a virtual keyboard to confirm payments at POS, which is saver. The confirmation options are 'password types' and can be and can be configured at System > User configurations > Password types.
  • Secondly you need to make sure there is a payment type from the customer to the shop, go to this payment type: System > Accounts configuration > Account types > [Select the account used, e.g. Member account] > Transfer types (tab) > [Select the payment transfer type you wish to use for payments made at the POS, e.g. User payment] > And do the following:
    • Make sure the transfer type is enabled.
    • In the "channels" field, make sure "Pay at POS" is selected.
    • In the "User identification methods" field, make sure nothing is selected (in this case all user identification methods are allowed). If you want to configure a dedicated transfer type for POS payments you can select the NFC card token you created in the earlier.

Don't forget to save.

Additional options

  • Confirmation password: For live systems it is recommend to have a confirmation password. The customer needs to enter this password to do the payment, e.g. his PIN. The transfer type has options to allow PINless payments with conditions (e.g. max single amount, max daily amount). Especially for NFC payments, which are more secure, PINless payments can make card payments easier for customers.
  • Virtual keyboard: It is good practice to use a virtual keyboard as confirmation password. This prevents that persons read your password/PIN by 'shoulder surfing' when you type, and it prevents screen-logging software to retrieve the password (because multiple characters/digits can be shown in one button). The virtual keyboard password can be the user product (General - Passwords). You can give the user permissions to manage his own passwords (Personal > Settings > Passwords). You can also do this as admin for him, then the admin must have the permissions over this password type too (Admin group - permissions - User management - Passwords). Finally you have to select the virtual keyboard as confirmation password in the "Pay at Pos" channel (Channel Tab in the configuration assigned to the user group). The "Pay at POS" channel does not define what identification method is used for the token/POS payments. This is configured at the POS / access client level (explained further below).

Step 2: Enable POS (access client)

In order for shops to be able to receive payments at a POS the following steps need to be done.

  • The user that will receive the payment (the shop) will need the permission to receive this specific transfer type, go to: System > User configuration > Products (permissions) > [open the product the shop uses, it needs to have an account configured ] > Accounts > Receive payments (POS) > And select the transfer type created above (e.g. card payment).
  • Where the card is represented by a 'token' in Cyclos, the POS is represented by an 'Access client' that needs to be activated in Cyclos and enabled in the POS (smart phone)
  • First an Access client needs to be created at: System > System Configuration > User identification methods > New > Access client, and fill in the necessary fields and save. When configuring the NFC POS, use the name "NFC POS". For access clients that are used by POS it is recommended to limit the permission level to either 'Receive only' or 'Receive and pay'. (Access clients are used for third party access to Cyclos, in other cases you will need to allow more permissions, but additional security can be applied. For POS access however the 'Receive only' or 'Receive and pay' are recommended).
  • Assign the Access client to the group of users (shops) that will use the POS device, go to: System > User configuration > Products (permissions) > [choose appropriate product] > My access clients > And make sure the NFC POS is enabled. For testing purposes it is easiest to select all boxes (view, manage, etc.), save the product.
  • Allow user to use the mobile app to login and make payments using an access client: System > System configuration > Configurations > [Select the configuration that is used by the shop, e.g. default for ..] > Channels (tab)> Mobile app > And make sure:
    • The channel is enabled.
    • It is easiest to also force the channel to be enabled, so the user cannot disable it himself: User access > Enforced enabled (user can access the channel but cannot disable it).
    • In "User identification methods" also select "NFC POS" (so that the mobile app can get access to Cyclos using the access client NFC POS).
    • Make sure that in the field "User identification methods for 'Receive payments (POS)', NFC card is selected and save.
  • Now the user that will use the POS (the shop) can login to Cyclos and go to: Personal -> Settings -> [The plural name of the POS, in this case NFC POS] > Add > The user have to fill in the name, for example the name or model of the phone e.g. "Samsung Galaxy S4 John" and click on save. Then the user needs to click on the button "Activation code" > Confirm, and write down the code.
  • After this the user (shop) will have to login into the mobile app, press the settings (cog) icon in the right top of the mobile app, and enter the validation code that was written down previously, and submit (verify if status in Cyclos changed from unassigned to active in the cyclos web).
  • Logout the mobile app and now an extra option is shown "Launch POS". When clicked on this button the POS will launch directly (without the need to login).

Additional information

  • You can also leave the activation of the POS to an administrator to make this process more safe, if you use this method the admin can verify the shop first and inspect the physical device before allowing it to be used as POS.
  • When using the POS functionality for receiving a payment it used the access client channel, when the shops pays a user it will us the Pay at POS channel. So be aware to set the correct passwords and identification methods in these channels.
  • Be aware that in order to make a payment between customer and shop there must exists a visibility between those users (products). The customer group needs to be able to view the shop, and the shop needs to be able the view the customer/payer. The visibility can be set in the product section: 'Accessibility and visibility of groups and users'.

Note: There are systems where a users will make payments at the POS as well as receiving payments, for example in the case of cash-in / cash-out services by the same operator. In this case the best would be to create a dedicated user group, configuration/channel and product and apply both Card as POS configurations to this configuration and product.

Step 4: NFC card initialization and personalization

The process of assigning a card to a user happens in two steps:

  1. Card initialization: Card initialization: Stores the three private keys into the card (PMK, AMK, APK) and stores the corresponding NFC key (token) in Cyclos with status UNASSIGNED.
  2. Card Personalization: Assigns the NFC token to the given user (it's a read-only operation against the card, it doesn't modify the card)

Card initialization

  • The card initialization can be done by an admin or broker when loging into the the POS mode in the Cyclos mobile app. After loggin in go to Manage NFC cards > Initialize and select the token. Optionally if you check the "Personalize" option and press Submit you can enter the name of the user on the top of the page to initialize and personalize a card. Please hold the card as close as possible to the back of the device.

Card Personalization The personalization can be done by brokers, admins, as well as normal members (shops). The personalization of card can be done by searching for the customer in the normal user search option (in the mobile app), going in to the user details and clicking on Personalize NFC card. When holding the card close to the phone the phone will detect it and ask for confirmation to personalize the card. A user can also be given permissions to create new users (at the mobile), at the registration page there is an option to personalize a card directly after the creation.

Note: If a card needs to be assigned to another user the card needs to be formatted first by an admin or broker, after which it can be initialized and personalized to the new user. The format option can be found at the card manage page. Usually new 'blank' cards are already formatted by the factory, meaning it is not needed to format them before initializing.

Card management from Web

  • As admin (or broker) you can go to the user profile and manage the tokens/cards: User management > [Name of the token].
  • The admin can search for all tokens/cards in the system going to: Users > Tokens > [Name of the token].
  • Admins can create multiple cards for a group of users at once using the import tokens feature: System - Tools - Imports and import a CSV with user and card numbers (see the Token specification import wiki for an example).
  • It is possible to import tokens and not assign them to users yet. For NFC tokens however the tokens will always need to be assigned to a user when importing.
    • Also users (e.g a shop) can personalize NFC cards for other users, then add the permission "Activate tokens for other users" to the product of the user that should activate the card (System > User configuration > Product (permissions) > [Product of the user] > Activate tokens for other users > check: newly defined token type). When a shop customizes a card for a customer, then the confirmation password (set in the Pay at POS channel of the customer) will be required.

Advanced NFC configuration


  • PMK (PICC Master Key): Required to format the card (i.e. erasing all the information stored on it).
  • AMK (Application MAster Key): Required to modify the card's data.
  • APK/OPK (Application key/Operational key): Operational key used to ensure the presence of the card in a payment or personalization (i.e. card operation).

Setting in cyclos.properties file

To avoid blocking cards with unknown PMKs, there is a new setting in the cyclos.properties file (documentation copied from the file):

### NFF Token Principal types (User identification methods) 
# The NFC types require an encryption key to allow the management of the corresponding NFC tokens.
# The following values (case-insensitive) are valid for the key generation:
# * random: Uses a cryptographically strong random number generator (RNG) to generate the key.
# * zero: Uses a fixed default key of 16 bytes long with all bytes in zero. This is the default.
# * <key>: Fixed custom key of 16 bytes long expressed in Hexadecimal notation, i.e. 32 Hexadecimal characters).
cyclos.nfcTokenTypeKey = zero

For development and testing, the value set is often zero (the default PMK) but for production (release) it's: random. In real tests and pilots this value should be changed to random but please ENSURE YOU FORMAT THE CARD THROUGH THE MOBILE APP BEFORE DELETING/RESTORING THE DATA FROM THE DATABASE. IF YOU LOOSE THE KEY STORED INTO THE CARD IT WILL BECOME USELESS.

In the mobile 1.4.3 we have two buttons: Initialize and Personalize, when press Initialize, if the NFC token type allows it you will see a check box to personalize too (i.e. allowing the user selection). The "Format" button will be shown only if you have the "Initialize" permission.

Bulk writing/personalization of cards

The above described flow of card personalization and initialization are manual and done one card at a time. In case it is needed to initialize and personalize large amount of cards this process can be automated. Cyclos has an API that allows initialize and personalizing cards. Companies that print & write cards could use the Cyclos API to write the cards. Another option is to buy a card printer that can write NFC tags. The printer software will need to connect to the Cyclos API to store the NFC keys. There are various printers that store NFC. An interesting option is Chipman software from the company http://www.mpsys.de/. This software works with various printer brands and models, and can write personalized cards (as well layout as NFC). Upon each card write the Chipman software does contact Cyclos via the API to store the NFC key.
A page with the details about the Cyclos POS/NFC API can be found at this wiki page NFC_cards_creation.

Step 5: Testing

  • to test if everything works correctly: click Launch POS > Receive payment > Enter the amount > And click "Select payer" > Hold the card as close as possible to the back of the device > enter the password and press confirm.
  • Login as the user that has permissions to recieve payments (shop) and go to Menu: Banking > Payments > Receive.
  • Select a user that has the permissions to perform a POS payment (customer) by typing in his username.
  • Type in an amount.
  • Submit the payment and confirm.

Note: When using cards with Barcode/QR you can just use a USB code reader and connect it to the PC/Tablet. When the cursor is in the Payer field the code reader will pass the ID in the field and the user will be identified.

Cyclos webPOS configuration guide

The Cyclos main Web channel allows POS (Point of Sale) payments from the normal web interface. In practice this allows shops or exchange offices that have a computer in their store to receive payments just by logging into the Cyclos website and by going to the receive payment page. In this example we use the username to identify the user at the POS. However any user identification method can be used, such as an account number, phone number, email or any unique profile field. Also a bar-code or QR-code can be used, in this case an USB Bar/QR-code reader can be purchased. When the code is scanned when the cursor is in the payer field, the string will be passed by the scanner and the user will be identified.

  • First follow Step 2: Enable POS (access client)
  • Allow the user that will receive the payment (the shop) to receive payments through the main web channel, go to: System > System configuration > Configurations > [Select the configuration that is used by the shop, e.g. default for ..] > Channels (tab)> Main > Make sure "Login name" is selected in the field "User identification methods for receiving payments".