Fidelia POS API

The Fidelia POS API lets a cash register work with the loyalty cards of Fidelia shops. The cashier scans the customer’s card (in Apple Wallet, Google Wallet or on a web page) and the till updates it: no second device, no typing.

How it works at the till

The cashier scans the card. Your scanner reads a QR code (a 32-character serial) or a barcode (a 13-digit card number), depending on the shop’s choice.
The till calls GET /cards/{code} and shows the customer’s first name, what is on the card, and any reward ready to use. Memberships return the discount to apply to the basket.
If a reward is ready, the till asks “Use reward now?”. One tap calls POST /cards/{code}/rewards/{id}/redeem, and Fidelia answers with the POS product the shop linked to that reward.
For cashback and prepaid cards, the cashier can pay with the card balance (Use all or an amount): POST /cards/{code}/balance/spend. Treat it as a payment line.
When the receipt is closed, the till sends POST /cards/{code}/sale with the total and the receipt number. Fidelia applies the shop’s rules: a stamp, points, cashback or a check-in.
A refund within 24 hours calls POST /receipts/{receipt_ref}/reverse, and everything the receipt did is undone.

Card types

Type	On a sale	Other actions
`stamps`	+1 stamp (from the shop’s minimum amount)	redeem the reward when the card is full
`points`	points per amount spent	redeem a reward
`cashback`	credit, a percentage of what was paid with money	pay with the balance
`membership`	a check-in; apply `discount_percent` while active	renew / activate
`prepaid`	nothing	pay with the balance, top up (with bonus)
`pack`	nothing	use items, sell / activate a pack

You don’t need to handle each type for the basics: sale does the right thing for every card. Read At the till for the details.

The basics

Base URL: https://api.fidelia.se/pos/v1
JSON over HTTPS. Every response has an X-Request-Id header (give it to us when you ask for help).
Authentication: Authorization: Bearer fk_live_…, one key per till. Tills get their key by pairing with a 6-digit code.
Amounts are integers in minor units of the shop’s currency (EUR cents, SEK öre): 1250 is 12.50.
Texts (card and reward names) come in the shop’s languages; ask for one with ?lang=fr or Accept-Language.
The shop needs Fidelia Pro; without it the API answers 402 plan_required.

Getting access

Write to support@fidelia.se. You get a partner id (sent when pairing, so shops you bring are credited to you) and a sandbox: a test shop with one card of each type, a fk_test_ key and a sheet of test cards to scan. Then follow the quickstart.