Choose your integration
The voucher service exposes three distinct integration surfaces. Each one has its own trust model, its own scope set on the JWT, and its own guardrails. Pick the track that matches the system you are building — the per-track page walks you through the calls in the right order with the right precautions.
| POS | eCom | CRM | |
|---|---|---|---|
| Build target | Cash desks, in-store terminals | Online storefronts, web checkout | Customer / loyalty platforms |
| Trust class | Trusted | Untrusted | Trusted |
| Where it runs | Inside the store network, on a managed device | Browser-adjacent — code or its callers reach the public internet | Inside the operator's data centre |
| Plane | redemption | redemption | crm |
| Default scopes | check, load, redeem, refund | check, redeem, refund (no load) | customer.read, customer.write, customer.forget |
| Store-bound JWT? | Yes — token only works for the configured store | No — eCom is store-less | No — operates on the catalogue, not at a till |
| PIN required? | No — POS sees the customer present a code | Yes — every redeem/check carries the PIN | n/a |
| Customer-bound handles? | Yes — issued via loyalty-card lookup | Yes — same lookup endpoint | Manages the underlying customer + cards |
| Webhooks? | n/a | n/a | Receives bound-voucher lifecycle events (Phase 7) |
Continue with the track that matches your system:
- Trusted Build a POS integration
- Untrusted Build an eCom integration
- Trusted Build a CRM integration
Why the trust split matters
POS terminals sit behind the store network, run a managed OS, and are supervised by staff. We grant them the full redemption scope set — they can load a fresh voucher at the till, redeem it, and refund it. The JWT they carry is store-bound: a token issued to store A is rejected by store B.
eCom traffic, by contrast, reaches us from systems that face the public internet. Even when the storefront server is well-engineered, its neighbours — third-party JavaScript, browser extensions, hostile clients — are not. We deliberately narrow the eCom scope set (no load), require the PIN on every call that touches a voucher, and route requests through tighter per-voucher rate buckets. Treat any eCom client as if the next request might be hostile.
CRM clients are operator-internal — they sync the customer directory and assign vouchers to accounts. They never redeem; they live on their own plane so a leaked CRM token cannot drain a voucher and a leaked redemption token cannot rewrite a customer.
If you're not sure which track is yours, the rule of thumb is: does the code that calls our API run on a device the customer can touch? If yes, you are eCom-class — even if your back-end relays the call.
Cross-references
- API keys — how the admin issues a key for each track
- Token exchange — how the key becomes a JWT
- JWT claims — exactly which scopes / claims each track receives
- Threat model — what we defend against per surface