Getting started

Read this once before integrating. It covers the two environments, how authentication works, the identifiers used throughout the API, and the idempotency model.

Environments

Env	Base URL	Notes
Sandbox	https://api-sandbox.mozrest.com	What Blitz integrates against today. Live against the mozrest-pos simulator at pos.sandbox.mozrest.com.
Production	https://api.mozrest.com	After sandbox sign-off, Mozrest provisions production credentials separately.

Authentication

Mozrest provisions a fixed, non-expiring bearer token per partner. There is no token refresh, rotation, or short-lived credential flow - the same token is valid until Mozrest explicitly revokes it. Pass it on every request:

Authorization: Bearer <token>

The token is partner-wide, not per-venue. All venues in your scope are accessible with the same token. If a token is compromised, contact support@mozrest.com to revoke and reissue.

A request to a venue outside the token's scope returns 403 Forbidden. A missing Authorization header also returns 403; an invalid or revoked token returns 401 with an OAuth-style body - see Errors for the exact shapes.

Identifiers at a glance

Field in this doc	What it is	Where you get it
venueId	Mozrest's canonical venue identifier (24-char hex, Mongo-style)	GET /v1/pat/venues - call this once at onboarding to learn your venue scope
tableId	Mozrest's canonical table identifier (UUID, stable per table per venue)	GET /v1/pat/venue/{venueId}/tables
orderId	The open order on a table (UUID)	GET /v1/pat/venue/{venueId}/table/{tableId}/bill response (orderId field)
externalReference	Your partner-side transaction ID	You choose. Unique per partner. Becomes the idempotency key on the payment endpoint and the lookup key on the payment status endpoint
posCode	Family code of the underlying POS (e.g. MOZREST_POS, SIMPHONY, LIGHTSPEED_K_SERIES)	GET /v1/pat/venues per-venue, or GET /v1/pat/venue/{venueId}/features for the full capability matrix - useful if you want to vary UX by POS

tip

venueId, tableId, and orderId are Mozrest IDs

They are stable, canonical, and the same value regardless of which POS sits behind the venue. Never substitute a POS-native ID - your integration would break the moment a venue switches POS.

Idempotency

The payment endpoint is the only write call. Replay protection is keyed on externalReference:

• Repeating a request with the same externalReference against the same orderId returns the payment's current state with response header X-Idempotent-Replay: true. The HTTP code matches that state: 202 Accepted while the payment is still pending (deferred-confirmation venues only), 200 OK once it is terminal.
• A different payload with the same externalReference against the same orderId returns 409 Conflict. Replay detection is scoped per order - the same externalReference on a different order is treated as a new payment, so keep references globally unique on your side.

This makes safe client retries on network failure straightforward - replay the exact same request body, you get the payment's state without any risk of double-charging.

Payment confirmation at a glance

Every payment carries a status - pending, confirmed, or failed - and the integration loop is the same everywhere: POST the payment; if the response status is "confirmed" or "failed" you are done; otherwise (202 Accepted / "pending", only on deferred-confirmation venues) poll GET …/payment/{externalReference} every ~1 second until it is terminal. Every payment is guaranteed terminal within 120 seconds. Details: Submit payment → Payment lifecycle.