Paperless POS Integration Spec

A self-contained specification for building a POS integration against the Paperless digital-receipt platform. Hand this document to your engineering team; they should not need access to the Paperless source code to implement a compliant integration.

What is Paperless?

Paperless is a digital-receipt pipeline. Whenever a customer makes a purchase at a merchant using your POS, the POS notifies Paperless, Paperless retrieves the full transaction details, identifies the customer, and stores the receipt so the customer can access it in the Paperless mobile and web apps. The customer never has to receive a paper or email receipt again.

Customer pays at merchant │ ▼ ┌──────────────┐ signed webhook ┌────────────────┐ │ Your POS │ ────────────────────▶ │ Paperless │ │ │ │ ingest layer │ └──────────────┘ └────────┬───────┘ ▲ │ │ GET /orders/{id} (Pattern A only) │ └────────────────────────────────────────┘ │ ▼ ┌────────────────┐ │ Worker queue │ │ + receipt DB │ └────────┬───────┘ │ ▼ Customer mobile & web apps

Two integration patterns

We support two integration shapes. Read Integration models for the full comparison and pick whichever fits your platform.

Pattern A — Full integration Bidirectional

OAuth · order pull · webhooks · token refresh

Your POS exposes an OAuth 2.0 server and an order-fetch API. Paperless connects each merchant via OAuth and pulls full order details when your POS notifies it of a new transaction. This is the same shape Square, Clover, and Lightspeed use.

Best for: high-volume merchants, rich order data, multi-location merchants.

Read Pattern A →

Pattern B — Push mode One-way

Signed receipt push · no OAuth · no order pull

Your POS POSTs a fully-formed, signed receipt payload directly to Paperless after each completed sale. No OAuth server, no order API to host, no token refresh. Simpler to ship — fewer features.

Best for: simpler POS platforms, low-volume merchants, MVP rollouts.

Read Pattern B →

How to read this document

Architecture — system overview, data flow, glossary.
Integration models — choose Pattern A or B.
Implement the chosen pattern: Pattern A or Pattern B.
Both patterns share the webhook contract, payload schema, and customer matching chapters.
Review Security before go-live.
Run the testing checklist.
Use the API reference as a lookup while coding.

Conventions used in this document

The placeholder {provider} stands for your POS's short name (e.g. acme).
All monetary values are integer cents (or the equivalent smallest unit) plus an ISO 4217 currency code.
All timestamps are ISO 8601 with timezone. UTC is preferred (suffix Z or +00:00).
All HMACs are SHA-256 with a per-provider signing key.
All API responses are JSON with Content-Type: application/json.

Getting in touch

Questions, signing-key requests, sandbox credentials, and onboarding go through your Paperless solutions engineer. Save that contact before you start; you will need it for the first end-to-end test.