Cardy Cardy Loyalty API
Run a loyalty programme from your point of sale: look a customer up, award points for a sale, spend them, and refund cleanly when something goes back.
Start here:
| Quickstart | Your first points awarded, in about fifteen minutes. |
| Your test card | A real sandbox card, as a QR your scanner can read. |
| Errors | Every code, what the cashier should see, what your code should do. |
| Certification | What we check before you go live, and how to run those checks yourself. |
| Changelog | Every partner-visible change, newest first. |
| Postman collection | Every endpoint, ready to import. Set apiKey and go. |
| OpenAPI | The machine-readable contract. Generate a client from it. |
The four things worth knowing before you write code
Your receipt number is the idempotency key. Send it as external_ref on
every write. Retrying with the same one is always safe and can never pay a
customer twice; retrying with a new one is the only way to double-award, and
nothing will warn you. This one rule removes most of the error handling you
would otherwise write.
Money is an integer plus a currency. KWD has three decimals, so 12.500 KWD
is amount_minor: 12500. There are no decimal amounts anywhere in this API.
Build your buttons from allowed_operations. The identify response tells
you what each card can do. Everything in that list will work; anything absent
will be refused.
What your scanner reads is the whole identifier. A card's serial —
947706-732-680 — is what the barcode carries, what you send as loyalty_id,
and what comes back as card_id. One string, no parsing, no prefix to strip.
Test the scan path first: it is the one your cashiers will actually use, and the
one that outranks every other identifier when two disagree.
Sandbox
https://sandbox.getcardy.net/api/v1
Your test key (cardy_pk_test_…) reaches the sandbox and nothing else. There is
no configuration mistake that lets a test key touch a real customer's balance.
We give you a customer who already holds eleven cards — one of every kind we support — so you can try a stamp card, a points card and a cashback card without setting anything up. Your test card is one of them, printed as a QR you can scan off the screen.