Developer guide · POS integration
Connect a POS without losing transaction control.
The POS owns the sale. Reward Loyalty supplies staff workflows and supported API surfaces; the integrator chooses the handoff, protects credentials, and reconciles uncertain writes.
- System of record
- POS sale and payment
- Machine path
- Scoped Agent API key
- Fallback
- Manual staff workflow
Short answer
Keep the sale in the POS.
A POS loyalty integration can use the manual staff workflow, the Agent API for server-to-server work, or the session-token REST API for documented partner purchase and staff cashier operations. Every session token remains constrained to role-specific routes. The POS owns the sale and its payment state. Reward Loyalty records the loyalty action. There is no universal POS connector: a POS that can call HTTPS APIs needs middleware or a native adapter built and maintained by the integrator.
Decision criteria
Choose the smallest supported handoff.
Start with who performs the action, which system owns the transaction, and what the checkout can do after an uncertain response.
Checkout capability
Confirm whether the POS can make server-side HTTPS calls, expose an extension point, or only run beside the staff interface.
Identity key
Choose the member identifier the cashier can collect and map it to the Reward Loyalty member without exposing another business’s records.
Failure policy
Decide what the cashier sees after validation, timeout, insufficient balance, duplicate action, or a loyalty service outage.
Integration path
Match the interface to the actor.
The best path is the one the checkout can secure and the operator can support.
Manual staff flow
Use the shipped staff interface beside the till when no integration is required. Staff can process supported earning and redemption work after identifying the member.
Agent API
Use a partner-owned key with narrow scopes for machine-to-machine member reads, purchase writes, and supported reward or voucher actions.
Session-token REST API
Use the locale API for a documented partner purchase or staff cashier action through a custom product client. Member and administrator tokens stay limited to the role-specific routes documented for them.
POS adapter or middleware
Build a thin server-side adapter when the POS exposes HTTPS or extension hooks. Keep the Reward Loyalty key outside the terminal browser and mobile client.
Data ownership
Move identity without moving payment authority.
Reward Loyalty should receive the loyalty fact it needs, not become the POS ledger.
Source transaction
The POS owns the sale, amount, payment capture, void, refund, receipt, tax, and external order reference.
Member identity
Resolve the member with a supported identifier, then keep the returned member and card identifiers for the loyalty workflow.
Partner boundary
A partner key and its scopes constrain the business and permitted action. Card, reward, voucher, staff, and transaction records are checked against that owner.
Brand presentation
White-label relevance: Supporting. Business and installation branding can support the operator’s offer; custom POS screens and adapter maintenance remain the buyer’s work.
Checkout flow
Separate reads, writes, and notifications.
A webhook can confirm a committed event. It cannot replace the write that creates it.
-
1
Resolve before payment
Look up the member, card balance, eligible reward, or voucher state needed for the cashier decision.
-
2
Commit the sale in the POS
Complete the source transaction under the POS policy before sending a purchase award tied to its external reference or note.
-
3
Write the loyalty action
Use the documented purchase, reward, deduction, stamp, or voucher operation with the scope required for that action.
-
4
Notify and reconcile
Use outbound webhooks as post-event notification where useful, then compare POS references, Reward Loyalty transactions, and exception logs.
Production controls
Design for an uncertain write result.
Checkout reliability depends on what the adapter does when it cannot tell whether a command committed.
Least privilege
Store the Agent API key on a trusted server, grant only required scopes, validate inputs, and keep a tested revocation route.
Non-idempotent writes
Purchase and redemption commands are non-idempotent. After a timeout, query or reconcile the transaction before sending the command again.
Voucher order
Validate before checkout, apply the benefit in the POS, and mark the voucher redeemed only after the sale is final. Define compensation for each failure point.
Monitoring
Record correlation and external references, watch structured API errors and rate responses, review Agent audit records, and alert on reconciliation gaps.
Product and operating limits
Do not turn an endpoint into a connector claim.
- Reward Loyalty does not ship a universal connector, drop-in SDK, or managed POS implementation. The buyer owns adapter development, terminal testing, deployment, and support.
- A webhook is a notification path. It cannot award points, reserve a reward, approve a redemption, or settle the POS transaction.
- Source access allows deeper changes to the application. Those changes remain subject to the commercial license and create security, test, maintenance, and update work.
Implementation guides
Use current documentation for changing details.
Requirements, interfaces, settings, limits, and release behavior belong in the maintained product documentation.