POS integration connects the shop floor to payments, stock, accounting and e-commerce. The hard parts are offline behaviour, hardware, idempotency and daily reconciliation.
Key takeaways
- Define the source of truth for products, prices, stock and sales.
- Use idempotency keys for sales and refunds; a retry must not double-count.
- Test offline mode, reconnection and duplicate events.
- Model the state and the exceptions before building the happy path.
What the system must model
- Reconcile the till, card settlements and bank deposits daily.
- Secure the device, the API credentials and staff permissions.
How to build it
- Map the flow. Product → sale → payment → stock → accounting.
- Choose the integration. Provider API, webhook or middleware.
- Model the events. Sale, refund, void, stock adjustment and settlement.
- Handle offline. Queue locally and replay with idempotency.
- Test hardware. Printer, scanner, drawer and terminal.
- Reconcile. Daily close and variance investigation.
Design decisions
| Area | What to decide | Why |
|---|---|---|
| Catalogue | Products and prices | One source of truth |
| Sales | Events and idempotency | Retries must be safe |
| Payments | Terminal/provider | Settlement and fees |
| Stock | Real-time or batch | Prevent overselling |
| Offline | Local queue | Test reconnection |
| Security | Device and credentials | Least privilege |
Controls and reconciliation
- Keep an audit trail for money, tax and access changes.
- Make every event idempotent; retries are normal.
- Reconcile the provider, the ledger and the bank on a schedule.
- Test failure paths: declined payments, duplicate webhooks, refunds and partial payments.
- Document who owns finance, tax and technical support.
A minimum data model
| Entity | What it must hold | Why it matters |
|---|---|---|
| Customer | Identity, tax status, addresses, consent | Invoices and tax depend on it |
| Product/plan | Price, currency, tax code, effective dates | Prices change over time |
| Invoice | Lines, tax, due date, status | The legal record |
| Payment | Provider ID, amount, status, timestamps | Reconciliation |
| Credit/refund | Reason, amount, approval | Revenue and tax corrections |
| Audit event | Actor, action, before/after | Disputes and controls |
Launch checklist
- Test a full lifecycle: quote, invoice, payment, refund and credit note.
- Test a failed payment, a duplicate webhook and a manual retry.
- Reconcile a full day of transactions against the provider and the bank.
- Check tax rounding, currency formatting and negative amounts.
- Give finance a read-only view and a documented correction process.
- Monitor queue depth, failed jobs and reconciliation differences.
Failure modes to design for
| Failure | What the system should do | What to monitor |
|---|---|---|
| Duplicate webhook | Ignore by event ID; keep one ledger entry | Duplicate-event count |
| Payment timeout | Show an unknown state; reconcile, never assume failure | Pending payments |
| Price change mid-cart | Revalidate and show the new total | Price-mismatch errors |
| Partial refund | Adjust the invoice and tax proportionally | Refund reconciliation |
| Currency mismatch | Reject or convert with an explicit rate | FX differences |
| Job backlog | Alert before invoices or emails are late | Queue age |
Operational metrics
- Invoices created, paid, overdue and failed, by day.
- Reconciliation differences and the time to resolve them.
- Payment success rate by method and market.
- Tax and currency exceptions that required manual review.
- Time to close the month and the number of manual journals.
- Support tickets per hundred transactions.
Common mistakes
- Building the checkout before the billing state model.
- Trusting client-side amounts, currencies or tax rates.
- Ignoring refunds, credit notes and failed payments.
- Launching without daily reconciliation.
Frequently asked questions
Often yes, through an API or middleware. Check whether stock, prices, sales and refunds sync in both directions and how conflicts are resolved.
The POS should continue offline and queue sales. Test the replay, duplicate protection and stock reconciliation before relying on it.
Match the POS close to the provider settlement and the bank deposit. Investigate fees, refunds and timing differences.
A direct integration gives control but costs more to maintain. Middleware can be faster if it supports your POS and accounting system.
Sources and further reading
- Square developer documentation (developer.squareup.com)
- Stripe Checkout documentation (docs.stripe.com)
- NIST Secure Software Development Framework (csrc.nist.gov)
Related services
Building a billing or POS flow?
Describe the plans, currencies and payment methods. I will map the state model and the reconciliation points before you build.
How to cite this guide: Nur Hossain Repon, “Build a POS integration for your business: guide”, Nhrepon Portfolio, reviewed October 2026, https://nhrepon.com/posts/build-a-pos-integration-for-your-business-guide.





Comments
No comments yet.