Badges

The Badges page is where you keep track of who holds which NFC card: your employees, your students, the members of your club. It has three tabs — Members, Badges and API keys — and a badge is only accepted at your terminals once it is active and handed to a member.

What badges are

A badge is a Citizen Pay card — an NFC card, key fob or sticker — identified by the serial number of its chip, the same number a terminal reads when someone taps it. A member is a person who holds badges. One member can hold several (a card and a key fob, say), but a badge belongs to one member at a time.

Badges is part of the badge platform subscription. When your organization's billing includes the badge platform, the Badges entry appears in your sidebar. If it is not there, ask your Citizen Pay contact. Citizen Pay does not switch Badges off automatically when a subscription ends; your Citizen Pay contact will get in touch first.

Your badges pay with your organization's own token, which you issue yourself: an owner issues it from Token in the sidebar, where owners and admins can later change its name, logo and colour — see Your token. Badges needs that token: once your organization has issued it, the Badges page shows it at the top. Until then the page shows a warning instead and registering badges is disabled.

Members

The Members tab lists everyone who can hold a badge, with how many badges each one has. A member has three fields:

• Name — required, up to 120 characters.
• Email — optional. Two members of your business can't share an email address; capitals don't count as a difference.
• External id — optional, up to 120 characters. Your own reference for this person: an employee number, a student number, the id in your membership software. It has to be unique within your business, and it is what the CSV import and the API use to recognise someone.

Add a member with the create button, and open a member to edit these fields or to see and manage their badges. Delete removes the member for good. Their badges are not deleted with them: they stay on the Badges tab, unassigned, and stop being accepted at your terminals until you give them to someone else.

Importing members from a CSV

To load many people at once, import a CSV file. Download the template from the Members tab — it has one header line:

name,email,external_id
Anna Peeters,anna.peeters@example.com,EMP-0042
Tom Janssens,,EMP-0043

• The file can be separated by commas, semicolons or tabs; the separator is detected from the header line, so a file saved by Excel in any language works.
• Each row is matched against the members you already have — by external id first, then by email. A match is updated, anything else is added as a new member. A row with neither an external id nor an email is always added as a new member.
• When a member is updated, only the columns that have a value in the file are changed. An empty cell never wipes out what is already there.
• One import takes up to 5,000 rows. Split a bigger list over several files.

After you choose the file, the dashboard shows a preview: which rows will be added, which will update an existing member and which have a problem, with the reason on each. Nothing is saved until you confirm the import, and rows with a problem are skipped.

Badges

The Badges tab lists every badge registered to your business, with its serial, its label (an optional name of your own, such as "Spare card 3"), its status and the member holding it.

A badge has one of three statuses:

• Active — in use: the card is accepted, as long as the badge is assigned to a member.
• Blocked — switched off for now, for example while someone is suspended. The card is refused.
• Lost — reported lost or stolen. The card is refused.

What you can do with a badge:

• Assign it to a member, or reassign it: giving a badge to someone else simply moves it from its current holder.
• Revoke it, which takes it back from its member. The badge stays registered, without a holder, and keeps its status.
• Block and Unblock it.
• Mark lost when it goes missing, and Found when it turns up again. Unblock and Found both set the badge back to Active.
• Delete it, which removes it from your business and blocks the card: from then on it is refused at your terminals. To take a card out of use only for a while, block it or mark it lost instead, so it keeps its member and label.

Registering a badge here — one at a time, from a CSV file or through the API — enrols the card on your business's badge token automatically; nothing else is needed. For a tap to charge that token, the terminals in your places must use the same token for NFC — see NFC token.

Importing badges from a CSV

The Badges tab has its own template, with one line per card:

serial,label,member_external_id,member_email
04A23B1C5D6E80,Front desk,EMP-0042,
04:A2:3B:1C:5D:6E:81,,,tom.janssens@example.com
04 a2 3b 1c 5d 6e 82,Spare card,,

• serial is the chip's serial number in hexadecimal: 8 to 20 digits (an even number of them). Colons, spaces and dashes between the pairs are fine, and so are lower-case letters: the second row above is stored as 04A23B1C5D6E81, the form the dashboard shows.
• label is optional.
• To hand the badge to a member straight away, fill in member_external_id or member_email. The external id is tried first, then the email. Leave both empty to register the badge without a holder.
• A row that names a member who doesn't exist is an error: that badge is not created. Import your members first.
• A serial that is already registered is left as it is and reported in the preview.

The separator detection, the preview and the 5,000-row limit work exactly as for members.

API keys

If your member list lives in another system — an HR tool, a school register, your membership software — you can keep it in sync through the Citizen Pay API instead of importing files. The API keys tab is where you create the keys that system uses.

• Press the create button and give the key a name that says who uses it ("HR sync", for example).
• The key is shown once, right after you create it. Copy it into the other system then; the dashboard keeps only its first characters, so you can recognise it later but never see it again.
• The list shows each key's name, those first characters, when it was created and when it was last used.
• Revoke a key you no longer need, or one that may have leaked. It stops working immediately.
• A business can have at most 10 active keys.

Only owners and admins can create and revoke keys. What a key can do, and how to use it, is described in the Developers section.

Related pages