Stamp loyalty cards from any till.

Start

Quickstart

1. Get a till token. Either pair the till (recommended for products you ship to many shops), or ask the shop owner to open Dashboard → POS & API → Connect with a token and paste the mtc_live_… token into your settings.
2. Send the sale. When the cashier presses your loyalty button, send what they typed or scanned as code, plus your receipt number as orderRef and the total.
3. Show the answer. On success show explanation and customer.balance.progressText. On an error show error.message. If customer.suggestedAction is offer_reward, the customer has a full card.

Treat the token like a password. Keep it on your server or in the till's secure storage, never in a web page.

Connect

Pair a till

Pairing works like signing in to a TV app: the till shows a short code, the shop manager approves it from their MezaTap account, and the till receives its token. Nobody copies secrets, and the manager decides the branch and permissions.

1. POST /pairings with a deviceName. Show userCode big on the till, or render qrSvg so the manager can scan it.
2. The manager opens https://mezatap.com/connect (or scans the QR, which opens verificationUrlComplete), checks the till and taps Approve.
3. Meanwhile, poll POST /pairings/token every interval seconds. You get 202 while waiting and 200 with the token once. A second poll after that returns PAIRING_CLAIMED.

Codes expire after 10 minutes. Polling faster than interval returns SLOW_DOWN. If the manager declines, you get PAIRING_DENIED.

{
  "object": "pairing",
  "userCode": "B6DJ-MC29",
  "deviceCode": "mtc_dev_VaQacAkHcrt-yV-Es4_EtqZRY28…",
  "verificationUrl": "https://mezatap.com/connect",
  "verificationUrlComplete": "https://mezatap.com/connect?code=B6DJ-MC29",
  "qrSvg": "<svg …>",
  "expiresIn": 600,
  "interval": 3,
  "partner": { "name": "Your POS", "verified": true }
}

Tokens at a glance

Connect

Send the products

The till is the source of truth for the menu. Send all of it with PUT /catalog: one line per product with your own sku (product id), its name, and its category plus categoryId when you have one. The manager then ticks, for example, the category Main dishes in MezaTap and only sales with a main dish earn stamps.

• PUT replaces this till's list. Products it sent before and leaves out now are switched off, not deleted, so old receipts still read well.
• PATCH sends only what changed. "active": false removes one product.
• Up to 5,000 products and 2 MB per PUT. SKUs compare case-insensitively; the same SKU from two tills of one shop is one product.
• Prefer categoryId: rules point at cat:<categoryId>, so renaming a category in the till keeps the rule working.
• GET /catalog shows what MezaTap has, grouped by category, how many came from each source (bySource: till, sales, import) and when this till last synced.
• Optional, never blocking. Products sold before the first sync are learned from the sale's items and show up for the manager; once the till sends the same product with its sku, the till's line wins.
• Every sale, stamped or not, appears in the shop's till log with the reason (for example no qualifying product or PROGRAM_REQUIRED), so the manager can see why a customer got no stamp.

Connect

Stay in sync

GET /me is the till's whole loyalty setup in one answer: the cards, today's rule already worded in the shop's language, which products count, what the cashier may do, and whether setup is finished. It carries an ETag; send it back as If-None-Match and an unchanged setup is an empty 304.

• Call it on every page load and every refreshAfterSeconds. When the manager changes a rule, a day, a product list or a permission, the next call returns the new setup.
• setup.nextSteps lists what is still recommended, such as sync_catalog (required: false). setup.complete is true as soon as the till is paired: nothing blocks stamps.
• cards[].today has the weekday (0 is Monday, in shop.timeZone), today's stamps and a ready line such as “Today (Monday): 2 stamps per visit”. closed: true means no stamps today.
• cashier is what the manager allows on this till: canStamp, canRedeem, canChooseStamps, canPickItems and canUndo (within undoWindowSeconds).
• A 401 means the shop disconnected or paused the till: hide the loyalty button and offer to pair again.

Connect

Permissions

A till asks for permissions when it pairs. The manager can switch them off before approving, or later from the dashboard. Missing one returns INSUFFICIENT_SCOPE.

Call GET /me when the till starts. It tells you the shop, its branches, its cards and how each card earns, so you can show “1 stamp per €10” on your button before anyone presses it.

Connect

Find the customer

Send exactly what the cashier entered as code. MezaTap recognises the wallet QR content, the card number, the short code printed under the QR, a phone number in any format, or an email address. You never need to parse it.

• POST /identify is optional. Use it if you want to show the customer's name and balance before the sale is final.
• If a phone or email matches several cards, writes return AMBIGUOUS_CUSTOMER with a matches list. Let the cashier pick one and send its customerId instead of code.
• Shops with more than one card may need a programId. You get PROGRAM_REQUIRED with the options when that is the case.
• We only return the first name. Phone numbers and emails never leave MezaTap.

Sell

Add stamps

POST /transactions is the whole integration for most tills. Send the customer, your receipt number and what was sold. MezaTap decides how many stamps that is worth.

A sale that earns nothing (for example below the minimum spend) is not an error: you get 200 with status: "skipped" and an explanation to show. Use POST /transactions/preview with the same body to show what a sale would earn without writing anything.

Sell

Retries & duplicates

Networks drop. Two independent safety nets make retrying always safe:

• Idempotency-Key header. Any unique string of 8 to 120 characters. Send the same key again and you get the first answer back, with no second write. The same key with a different body returns IDEMPOTENCY_CONFLICT.
• orderRef. A receipt that already earned is refused with ORDER_ALREADY_PROCESSED, and the original transaction is attached so you can show it.

Rule of thumb: build the key from your sale id (sale-R-1042) and retry on timeouts, 429 and 5xx with the same key.

Sell

Refunds

When a sale is refunded, void it by orderRef or transactionId. The stamps come off the card. If those stamps had already been spent on a reward, MezaTap takes back what it can and tells you in reversedStamps. Voiding a redemption puts the stamps back (restoredStamps).

Transactions can be voided for 30 days. The shop can also undo a till transaction from its dashboard; you'll get a transaction.voided webhook.

Sell

Redeem rewards

When a match says suggestedAction: "offer_reward", offer the reward. If the customer accepts, call POST /redemptions. It takes one full card worth of stamps per count. Asking for more than the customer has returns NOT_ENOUGH_STAMPS.

Use an Idempotency-Key here too, so a double tap never redeems twice.

No-code

Cashier screen

Don't want to build any screens? Create a session for the sale and open its url in a popup, iframe or web view. The cashier scans or types the customer's code there, sees the balance, confirms, and can redeem a reward. MezaTap follows the shop's language and colours automatically.

• The link works once, for 15 minutes, and needs no login. Create it from your server: it carries the till's rights for that one sale.
• The screen shows today's rule and the order lines you sent in items. If you sent none and the rule depends on products, the cashier ticks the qualifying products from the catalog, when the manager allows it for this till.
• Right after stamping, the cashier can undo for 10 minutes (if allowed). The stamps come off, the sale reopens and a transaction.voided webhook is sent.
• When the cashier is done, the screen sends a postMessage to the window that opened it and to the React Native bridge, then follows returnUrl if you gave one.
• returnUrl gets mezatap_session, mezatap_status (completed or canceled) and mezatap_transaction added. App deep links such as yourpos://done work.
• Always confirm on your server with GET /sessions/{id} or the stamps.earned webhook before you trust the result.

const session = await createSession(sale); // POST /sessions from your backend
const screen = window.open(session.url, "mezatap", "width=480,height=760");

window.addEventListener("message", (event) => {
  if (event.origin !== "https://mezatap.com" || event.data?.source !== "mezatap") return;
  if (event.data.type === "session.completed") {
    // { sessionId, transactionId, stampsAdded, rewardUnlocked }
    markSaleStamped(event.data.transactionId);
  }
  if (event.data.type === "session.canceled") showOnTill("No stamps for this sale");
});

Events

Webhooks

The shop owner adds your HTTPS endpoint under Dashboard → POS & API → Webhooks, picks the events and gets a whsec_… secret once. Each delivery is a JSON POST signed with that secret.

Verify the signature

MezaTap-Signature: t=<unix seconds>,v1=<hex> where v1 is HMAC-SHA256 of `${t}.${rawBody}` with your secret. Reject timestamps older than 5 minutes to stop replays, and compare in constant time.

import crypto from "node:crypto";

// rawBody must be the exact bytes you received, before any JSON parsing.
export function verifyMezaTap(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}

// Express
app.post("/hooks/mezatap", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyMezaTap(req.body.toString("utf8"), req.get("MezaTap-Signature") ?? "", process.env.MEZATAP_WEBHOOK_SECRET)) {
    return res.sendStatus(400);
  }
  const event = JSON.parse(req.body);
  res.sendStatus(200); // answer fast, do the work after
  handle(event);
});

Delivery

• Answer with any 2xx within 8 seconds. Do slow work after you respond.
• Failed deliveries are retried after 1 min, 5 min, 30 min, 2 h, 6 h, 24 h. After 30 failures in a row the endpoint is switched off and the shop is told in its dashboard.
• Events can arrive twice or out of order. Use MezaTap-Event-Id to skip ones you already handled.