Arihant Global Ventures Inc. Machine-readable Markdown for this page: send Accept text/markdown, or open /guides/pos-integration-playbook/index.md. Site overview for language models: /llms.txt. Full guide text: /llms-full.txt.

Canadian enterprise & public-sector advisoryPrincipal-led deliveryToronto, ON, Canada

Arihant Global Ventures Inc.
Discuss an Assessment
← All guides

Guide · October 11, 2026 · 7 min read

The POS Integration Playbook: Connecting Third-Party Point-of-Sale Systems

A practical playbook for integrating third-party POS systems: OAuth token lifecycle management, webhook vs polling tradeoffs, normalizing provider data, and surviving provider API changes.

Enterprise ArchitectureIntegrationRetail TechnologyAPIs

Point-of-sale integrations look straightforward in the sales deck — “connect your POS, we handle the rest” — and turn out to be one of the most demanding integration categories in enterprise software. Each provider has its own auth model, its own event semantics, its own API quirks, and its own schedule for breaking changes. This playbook covers how to manage the token lifecycle, when to use webhooks versus polling, how to normalize wildly different provider data into one model, and how to structure the code so the next provider — or the next breaking change — does not require a rewrite.

1. The OAuth Token Lifecycle Is a System, Not a Step

Getting the OAuth token is the easy part. Keeping it valid across months of unattended operation is the system. Every POS integration needs four components around the token:

  • Encrypted storage. Tokens are stored encrypted at rest — AES-256-GCM is the standard choice — never in plaintext, never in logs. The encryption key itself lives in a secret manager, not in the codebase or environment files checked into version control. Key rotation should be possible without re-encrypting every token by hand; envelope encryption (a data key per token, wrapped by a master key) makes this manageable.
  • A refresh daemon. Access tokens expire — typically hourly. A scheduled job refreshes tokens proactively before expiry rather than waiting for a 401. Refreshing on failure alone means every expiry causes a failed request first, and a burst of failures when many tokens expire together. The daemon runs on a tight schedule, refreshes tokens nearing expiry, and updates the stored token atomically.
  • Per-connection health status. Each merchant’s POS connection carries a status: active, token expiring, refresh failed, disconnected. This status is visible to the merchant and to your operations team. A connection whose refresh has failed three times is not “probably fine” — it is broken, and someone needs to know before transactions stop flowing.
  • A reconnect flow the merchant can complete alone. Tokens get revoked — merchants change passwords, reinstall apps, revoke access during audits. The reconnect flow must be self-service: the merchant clicks reconnect, goes through OAuth again, and ingestion resumes. If reconnecting requires your support team, you have built a support ticket generator, not an integration.

The most common production failure is not exotic: a refresh daemon that silently stopped, or a token that expired over a long weekend with no alert. Monitor the daemon itself, alert on refresh failures per connection, and treat “no transactions in 24 hours from an active connection” as an anomaly worth investigating.

2. Webhooks vs. Polling: Use Both, for Different Reasons

Every provider offers some combination of webhooks (they push events to you) and API polling (you pull). The naive choice is webhooks-only because it is real-time and efficient. The production choice is both, with clear responsibilities:

  • Webhooks are the primary path. They give you near-real-time ingestion — typically under a minute from sale to processed transaction. Every webhook endpoint follows the reliability patterns: signature verification, fast acknowledgment, async processing, idempotency. (Our webhook reliability guide covers these in depth.)
  • Polling is the safety net. A scheduled job per connection fetches recent transactions from the provider’s API and feeds them through the same pipeline. Polling catches what webhooks miss: provider outages, your deploys, network partitions, events the provider never sent.

The two paths must converge on one processing pipeline — not two implementations of the same logic. The idempotency key (typically {provider}:{merchantId}:{providerTransactionId}) is what makes the overlap safe: an event delivered by both paths is processed exactly once.

Poll design details that matter:

  • Per-connection watermarks. Each connection stores the timestamp of the most recently ingested event. The poll job fetches everything newer than the watermark, then advances it. Build in an overlap window — two hours is a reasonable default — so late-arriving events are not skipped.
  • Per-connection failure isolation. If one merchant’s token is revoked, that connection’s poll job fails without affecting the others. Shared poll loops with a single failure domain turn one merchant’s problem into everyone’s outage.
  • Respect rate limits. Stagger poll schedules, back off on 429s, and design the poll interval around the provider’s limits — five minutes is plenty for a loyalty use case.

3. Normalize Early: One Transaction Model for Every Provider

Square, Clover, Toast, and Lighthouse describe the same real-world event — a customer paid money at a store — in four different data shapes, with different field names, different timestamp formats, different customer identity models, and different ideas about what constitutes a “transaction” versus an “order” versus a “payment.”

The adapter pattern solves this: each provider gets an adapter whose only job is to convert the provider’s raw event into your unified transaction model — provider name, merchant identifier, provider transaction ID, amount, currency, timestamp, and customer reference (email, phone, or provider customer ID). Everything downstream — identity resolution, reward calculation, ledger writes — operates only on the unified model and never touches provider-specific shapes.

Three rules for the normalization layer:

  • Normalize at the boundary, immediately. The raw payload is stored untouched for audit, and the adapter runs as the first processing step. Provider-specific logic must not leak past this point. If your reward engine has a if (provider === 'square') branch, the boundary has failed.
  • Version the normalization contract. Providers change their APIs — new event types, renamed fields, deprecated endpoints. The adapter is the single place that absorbs those changes.
  • Resolve customer identity from the normalized model. Each provider identifies customers differently. The identity step matches the normalized customer reference (email or phone) against your user records. Design for the common case where the provider gives you a phone number and nothing else.

4. Design for Provider Change

Provider APIs change on the provider’s schedule, not yours. Deprecation notices arrive by email to an address nobody monitors. A field you depend on disappears from the webhook payload. The integration keeps “working” but silently stops matching customers.

Defenses, in order of importance:

  • Monitor data quality, not just uptime. “The webhook endpoint returns 200” tells you nothing about whether transactions are being matched to customers. Track the rate of unmatched transactions per connection; a sudden spike means the provider changed something about customer data. Alert on it.
  • Keep the raw payloads. When a provider change breaks normalization, raw payload storage lets you see exactly what changed and replay history through the fixed adapter.
  • Abstract provider capabilities, not providers. Your code should ask “does this connection support discount write-back?” not “is this Toast?” — because the answer changes per provider and per API version.
  • Plan for the app-approval gauntlet. Some providers require a multi-week approval process before your integration can go live. Start the paperwork in parallel with development, not after.

5. Scope the Work Honestly

POS integrations are routinely underestimated because the demo — one OAuth flow, one webhook, one test transaction — takes a day. Production takes weeks per provider: the token lifecycle, the poll fallback, the adapter, identity resolution edge cases, the approval process, the monitoring. Multiply the demo by ten and you are close.

When scoping, separate the concerns: authentication and token management, event ingestion (webhooks), the safety net (polling), normalization, identity resolution, and provider-specific features. Each is independently testable and independently shippable. And price the ongoing cost: token refresh infrastructure, poll compute, monitoring, and the inevitable provider-change fire drill are operational expenses, not one-time build costs.

The Shape of a Good Integration

A well-built POS integration is boring in production: tokens refresh themselves, webhooks flow through the pipeline, polls catch the gaps, adapters absorb provider changes, and the merchant never thinks about it. Getting there requires treating the token lifecycle as a system, running webhooks and polling as complementary paths, normalizing at the boundary, and monitoring data quality rather than just uptime. Build it this way once, and the second, third, and fourth providers are genuinely easier — the pipeline, the patterns, and the operational muscle already exist.

For the ingestion pipeline internals — signature verification, fast-ack processing, idempotency keys, raw payload storage — see our webhook reliability patterns. If you are planning a POS or payment-provider integration and want the architecture designed right the first time, review our engagement models or contact us.

Start with a conversation.

A free 30-minute introduction to discuss your AI governance challenge, constraints, and whether we can help. No project brief required.

Contact us for current availability. Scope, timing, and fees are agreed before paid work begins.