POSZ DEVELOPER DOCS

Integrations

Build a Posz integration — receipt prompts, payment methods, delivery channels, accounting sync, anything that talks to a merchant’s POS.

SPEC VERSION v1 · 2026-05-02 STATUS Stable · additive only in v1 CONTACT posz@uncle-z.com

Overview

A Posz integration is a third-party service that plugs into a well-defined surface of the Posz POS — a printed receipt, a cashier checkout flow, a kitchen ticket, an accounting export, a reservation feed.

Each integration declares one or more capabilities (e.g. receipt_qr, pay_at_table) and a mode — either add (appends to a surface) or replace (takes over a surface completely). Posz’s dispatcher reads installed integrations at runtime and routes each surface to the right adapter.

Merchants browse the integrations catalog at posz.uncle-z.com/integrations, click Install, and configure per-merchant or per-location. Integrations are scoped independently — a merchant can run one provider in Jakarta and a different provider in Bali.

First time here?

Skip ahead to the SplitEasy example for a complete worked integration, or open the API reference for endpoint-by-endpoint detail.

Category	Description	Example partners
`order_channel`	Inbound orders + outbound order status + menu push	GoFood, GrabFood, ShopeeFood, ChowNow, Olo
`reservations`	Bookings + waitlist sync	Chope, OpenTable, Resy, SevenRooms
`payments`	Methods, pay-at-table, tax invoice provider	Kredivo, Akulaku, Qlub, Sunday, e-Faktur
`receipt`	Anything attached to the printed/digital receipt	SplitEasy, Splitwise, Google Reviews, NPS, coupons
`loyalty`	Points + rewards programs	Tada, Astra Points, Smile.io
`crm`	Customer + event export to marketing tools	Mailchimp, Klaviyo, ActiveCampaign
`notifications`	Outbound channel provider swap	Wati, Qontak, Twilio, MessageBird
`accounting`	Order/refund export to bookkeeping	Jurnal, Accurate, Xero, QuickBooks
`hr`	Staff + scheduling sync	Mekari Talenta, 7shifts, Sling
`inventory`	Replenishment + supplier APIs	Crisp, BlueCart, Marketman
`analytics`	Data exports to BI	Metabase, Looker, BigQuery, GA4

Capabilities

Capabilities are the named hooks Posz exposes. Each one corresponds to a specific dispatch point inside Posz’s runtime — the receipt printer, the checkout screen, the order-paid event, etc.

Capability	Surface	Mode	Status
`receipt_qr`	QR/text appended to printed + digital receipt	add (max 3)	live
`receipt_pretext`	Text block above receipt totals	add (max 1)	reserved
`payment_method`	New choice on cashier checkout screen	add	reserved
`pay_at_table`	Replaces Posz’s diner-side per-guest QR pay	replace	reserved
`payment_webhook_inbound`	Provider posts back when a charge captures	add	live
`tax_invoice_provider`	Replaces Posz’s built-in NPWP counter	replace	reserved
`reservation_provider`	Pushes bookings into Posz reservations	replace	reserved
`reservation_status_outbound`	Posz tells provider seated/no-show	add	reserved
`order_inbound`	Aggregator pushes orders into Posz	add	reserved
`order_status_outbound`	Posz tells aggregator order ready	add	reserved
`menu_sync_outbound`	Posz pushes menu deltas to aggregator	add	reserved
`loyalty_provider`	Replaces Posz internal loyalty	replace	reserved
`customer_export`	Push customer profiles to CRM	add	reserved
`customer_event_export`	Push behavioral events to CRM	add	reserved
`notification_provider`	Swap WhatsApp/SMS/email infrastructure	replace	reserved
`inventory_event_export`	Push stock changes to procurement	add	reserved
`inventory_replenish_inbound`	Receive PO/receive-goods events	add	reserved
`staff_event_export`	Push shift/clock events to HR	add	reserved
`staff_schedule_import`	Pull shift schedule from HR	add	reserved
`data_export_destination`	Bulk data export to BI	add	reserved
`auth_provider`	SSO replace for owner login	replace	reserved

Live vs reserved

live = Posz dispatches to adapters today. reserved = capability is in the schema and recognised; an adapter ships when the first real partner needs it. Adding the adapter typically takes a few hours per capability.

Authentication

Posz supports three auth shapes. Each integration declares one in its catalog row; the dashboard install UI adapts accordingly.

`platform_shared`

One 32-byte secret shared between Posz and the partner at the platform level. Every Posz merchant signs their JWTs with the same secret. The partner trusts “came from Posz” without per-merchant onboarding.

When to use: the partner is consumer-facing and has no merchant account model (e.g. SplitEasy, where diners use the app, not merchants).

`merchant_key`

Each merchant gets their own API key/credential issued by the partner. Merchant pastes the key into the Posz install drawer. Posz stores it encrypted in merchant_integration.config.

When to use: the partner already has a merchant portal and identity model (e.g. Qlub, Mailchimp, Jurnal).

`oauth`

Standard 3-leg OAuth 2.0 dance. Merchant clicks Connect → redirected to partner authorize URL → returns to Posz with code → Posz exchanges for token. Token stored encrypted, refreshed per partner spec.

When to use: the partner exposes user-scoped OAuth (e.g. Google Reviews, Xero, QuickBooks).

Secret hygiene

Shared secrets rotate quarterly via 1Password share with a 5-minute coordinated cutover (both old + new accepted during the window). Never commit secrets to source; never share via plain email or unencrypted chat.

Install lifecycle

Three states a merchant’s integration can be in:

Discoverable — present in catalog, not installed. Merchant sees it on /integrations.
Installed + enabled — actively dispatched. Per-merchant or per-location.
Disabled — soft state. Config preserved; surface is no longer dispatched. One-click re-enable.

Uninstall is destructive (removes the install row + erases config). Re-installing later starts fresh.

Per-location scope

Every install row has an optional location_id. NULL means “applies to every location” (default). A merchant can also install the same integration per-location with different configs — useful when only some outlets use a given provider.

Mode conflicts

Two integrations with replace mode on the same capability + same location → the second install returns 409 Conflict with a clear message. Uninstall the first to install the second. add mode is unconstrained, capped per capability (e.g. receipt_qr max 3).

Webhooks

Outbound from Posz

Posz emits domain events (order paid, refund created, settings changed) to integrations subscribed via the payment_webhook_inbound family of capabilities. Delivery is signed with HMAC-SHA256 in X-Posz-Signature, with retries at 1m/5m/15m/60m envelope.

Inbound to Posz

Partners post events to https://api.posz.uncle-z.com/v1/integrations/{slug}/webhook. Sign with HMAC-SHA256 of the raw body using the per-integration secret, send in X-{Slug}-Signature header.

Replay-safe

Posz dedupes by (merchant_integration_id, provider_event_id). Always include a unique event ID — replays return 200 (deduped) for known IDs, so retries are safe.

Errors

Posz’s public API returns errors as {"error": {"code": "...", "message": "..."}}. Standard codes:

invalid_signature — webhook HMAC failed
integration_not_installed — slug correct but merchant has no install
integration_disabled — installed but soft-disabled
capability_unsupported — slug doesn’t expose the requested capability
config_invalid — install config doesn’t match schema
rate_limited — per-tenant or per-integration rate cap hit
upstream_error — partner API returned non-2xx; Posz retries per envelope

Versioning

Public integration APIs live under /v1/integrations/.... Within v1 we add fields and capabilities additively — never rename, never remove. Breaking changes bump to /v2/...; the prior version stays alive at least 12 months past the breaking-version launch.

Each capability also has an internal version (capability_version on the catalog row). Adapters declare which version they speak. If we ever need to break a capability contract, we bump the version and route old installs to the old adapter until partners migrate.

Submit an integration

Today: email posz@uncle-z.com with what you’re building and which capabilities you need. We’ll add a catalog row, share keys/secrets out of band, and turn your slug to available when you’re ready to receive merchant traffic.

Future: self-serve submission via a partner portal. We’ll ship that when there’s a queue worth managing.