Real-time verification

Flow

How a coupon travels from your app to a Brizz checkout and back — read left to right. The one box on your side during checkout is what makes Model C different; everything after it is standard Brizz machinery.

What you need from your side

• RequiredA public HTTPS endpoint with valid TLSPlain http:// is rejected before a connection is opened, as are private, loopback, link-local, CGNAT, cloud-metadata and multicast addresses — IPv4 and IPv6 alike. A hostname that resolves into one of those ranges is rejected too.
• RequiredA bearer credentialSent as Authorization: Bearer <secret>, or as X-API-Key: <secret> if you prefer — those are the only two header names accepted. Brizz issues it: generated and revealed once, sent to you out of band. (You may instead supply your own.)
• RequiredAn implementation of the contract belowTypically a thin lookup against your own coupon store — see the minimal implementation further down.
• RequiredA routing ruleA code prefix such as PARTNER-, or a prefixless mapping tied to specific events, so Brizz knows which codes to route to you.
• RequiredA latency commitmentDefault timeout 1500 ms, configurable between 100 and 5000 ms — a value outside that range is clamped into it, not rejected. Brizz also applies its own ceilings of 5 s to connect and 10 s in total. Slower than the timeout is treated as unavailable.
• OptionalAn HMAC signing secretStrongly recommended: it lets you verify a request genuinely came from Brizz rather than trusting the bearer alone. Brizz issues this one too. The redemption webhook is signed with a separate, always-Brizz-issued HMAC secret — so with signing on both channels there are three Brizz-issued secrets in total.

Which codes reach you

Brizz decides whether to call you from the code alone, before any outbound request. A code is uppercased and trimmed, then it must be 4–32 characters of A–Z, 0–9 and hyphen. Brizz then routes it to you by one of two rules you choose: a prefix token matching [A-Z0-9]{2,16}- (the trailing hyphen is part of the token), or a prefixless mapping tied to specific events — in which case a bare code with no prefix (e.g. SUMMER10) still routes to you.

The request Brizz sends

Content-Type: application/json
User-Agent: Brizz-Verification/1.0

Authorization: Bearer <secret>       # or: X-API-Key: <secret>

# if HMAC signing is enabled:
X-Brizz-Timestamp:  1784654651
X-Brizz-Request-Id: <uuid>
X-Brizz-Signature:  v1=<hex>

{ "code": "PARTNER-AB12", "campaign_uuid": "…", "request_id": "<uuid>" }

No customer PII leaves Brizz. You issued the code to a specific person, so the code is already your user reference — you can answer “is this valid, and is this user new to us” from your own records alone.

Keep request_id in your logs. It is the handle Brizz support uses to correlate one specific call with your side, and it is in the body of every request — the X-Brizz-Request-Id header carries the same value but is only sent when signing is enabled.

Verifying the signature

signed_payload = "{timestamp}.{request_id}.{raw_body}"
expected       = HMAC_SHA256(your_hmac_secret, signed_payload)

Use the raw body exactly as received — do not re-serialise the JSON. Compare in constant time against any v1= candidate (multiple appear only during rotation), and reject if |now − timestamp| > 300 s.

The response you return

Exactly HTTP 200, application/json, at most 64 KiB. Anything else — another status, a non-JSON body, a timeout — is treated as unavailable: no discount, and checkout continues normally.

# approve
{ "approved": true, "authorization_ref": "ptr-9f2c…", "reason": null }

# deny
{ "approved": false, "reason": "ALREADY_USED" }

• approved — Required, strict JSON boolean. A truthy string or number is rejected as malformed.
• authorization_ref — Optional on approval. Opaque, ≤128 characters, no PII. Over-length keeps the approval but drops the reference — we never truncate it, because a truncated identifier can collide.
• reason — Optional, ≤256 chars, resolved against a CLOSED vocabulary: INVALID · EXPIRED · ALREADY_USED · NOT_ELIGIBLE · REVOKED. Matching is forgiving about case, whitespace, hyphens and dots, so “already used” and “Already-Used” both land on ALREADY_USED. Never shown to the customer.
• money fields — discount, amount, price, value, discount_eur and discount_cents are read for a bounded metric and then discarded — never persisted, and never used to price anything. Brizz prices from the campaign's own budget config, under a lock. Your endpoint answers yes or no; it cannot set the discount.

A minimal implementation

POST /verification:

  1. authenticate
     if header(Authorization) != "Bearer " + OUR_SECRET  → 401   (constant-time)

  2. verify signature, if you enabled HMAC
     payload = timestamp + "." + request_id + "." + raw_body
     if no v1= candidate matches HMAC_SHA256(secret, payload)  → 401
     if abs(now - timestamp) > 300                             → 401

  3. look the code up in YOUR store
     coupon = find(body.code)
     if !coupon        → 200 { approved: false, reason: "INVALID" }
     if coupon.used    → 200 { approved: false, reason: "ALREADY_USED" }
     if coupon.expired → 200 { approved: false, reason: "EXPIRED" }

  4. approve
     return 200 { approved: true, authorization_ref: coupon.id }

Failure behaviour, and the circuit breaker

Every failure resolves the same way for the customer: no discount, full price, checkout continues. What changes is what Brizz does next.

Five failures inside a 300-second window trip the breaker; any success in between clears the count. Once tripped, Brizz stops calling you for a 60-second cooldown and denies locally. After the cooldown exactly one request probes you — everything else keeps failing closed until that probe resolves, and a failed probe re-opens the breaker immediately.

What Brizz stores

We never receive or hold your code universe — we only learn a code when a customer actually types it. On approval Brizz materialises that single code as one row, marked as originating from real-time verification, carrying your authorization_ref. That row is the only double-spend defence there is: without it there is nothing to lock, so two concurrent checkouts could each spend the same code. It is also what lets the existing budget-cap, per-user-limit, webhook and reporting machinery treat your codes exactly like any other.

Verification itself creates no coupon, reservation, booking or payment record. Brizz may write bounded operational telemetry — a keyed hash of the code plus an outcome category, never the raw code or your reason text. The short-lived approval cache is likewise keyed by that hash, never your raw code, and any change to your endpoint configuration discards cached approvals immediately rather than waiting for them to expire.

After approval: redeemed, or not

Your endpoint is called while a customer is mid-checkout, so an approval is a reserve-time answer — not proof the code was spent. The customer may still not pay. You learn the real outcome after checkout, and only for the codes that are actually redeemed.

A later refund or cancellation is not pushed either — it appears in the reconciliation report alongside the redemptions, which stays the source of truth for what you are owed.

Build checklist

Everything above, in one screen — the checklist to build and verify your endpoint against before you go live.

Before go-live

Brizz runs a synthetic Test connection against your endpoint. It uses the same transport, the same request body and the same signing as production, so it exercises the full wire — URL, TLS, auth, HMAC and response shape — with the code BRIZZ-CONN-TEST, prefixed with your route's prefix when one is configured.

That code cannot match anything on the Brizz side, so answering approved: false still passes. Your approve/deny answer is discarded entirely; only reachability and protocol shape are reported.